diff --git a/README.md b/README.md index ef348d3..37c1cb5 100644 --- a/README.md +++ b/README.md @@ -70,7 +70,7 @@ const config = createConfiguration({ }, }) const authApi = new ObjectAuthApi(config) -const { tenant } = await authApi.getV2AuthWhoami() +const { tenant } = await authApi.v2AuthWhoamiGET() console.log(tenant.name) ``` @@ -91,7 +91,7 @@ const companiesApi = new CompaniesApi(config) for await ( const page of paginated( - companiesApi.getV2Companies.bind(companiesApi), + companiesApi.v2CompaniesGET.bind(companiesApi), )({ limit: 10, }) diff --git a/openapi/2025-03-12.json b/openapi/2025-11-26.json similarity index 58% rename from openapi/2025-03-12.json rename to openapi/2025-11-26.json index 0a2e310..282cb4d 100644 --- a/openapi/2025-03-12.json +++ b/openapi/2025-11-26.json @@ -1,13 +1,14 @@ { - "openapi": "3.1.0", + "openapi": "3.1.1", "info": { - "version": "2024-01-01", + "version": "", + "x-affinity-api-version": "2024-01-01", "contact": { "email": "support@affinity.co", "name": "Affinity Support", "url": "https://support.affinity.co" }, - "description": "# Introduction\n\nWelcome to Affinity API v2! This API provides a RESTful interface for building internal apps,\nautomated workflows, and other integrations on top of the core data models in Affinity, and for\nconnecting Affinity to the rest of your tech and data stack.\n\nPlease note that this new version of the API is not at feature parity with\n[Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of\nv1's functionality over time. **This API version is also only available on select Affinity license\ntypes.** See\n[this Help Center article](https://support.affinity.co/hc/en-us/articles/5563700459533-Getting-started-with-the-Affinity-API-FAQs)\nor contact your Customer Success Manager for more information.\n\n# Getting Started\n\nAll Affinity API endpoints use the base URL `https://api.affinity.co`. All v2 endpoint paths start\nwith `/v2`. Requests must be sent over HTTPS.\n\n## Using These Docs\n\nThe first few sections of these docs cover general information on the API. Each subsequent section\ncovers a set of API endpoints.\n\nEach endpoint is documented with its accepted request parameters, expected response shapes, and a\nsample request and response. Please note that the shape of a given response can vary depending on\nwhat \"type\" of object or data is being returned. When this is the case, the response documentation\nwill include a dropdown that can be used to select the \"type\" for which to display the response\nshape.\n\n## Authentication\n\nAffinity API v2 uses API keys and **bearer authentication** (this is an important difference from\nAffinity API v1's use of basic authentication).\n\nTo generate an API key, navigate to the Settings page in the Affinity web app. You will need the\n\"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this.\nSee\n[this Help Center article](https://support.affinity.co/hc/en-us/articles/360032633992-How-to-obtain-your-API-Key)\nfor full instructions on API key generation, and\n[this article](https://support.affinity.co/hc/en-us/articles/360015976732-Account-Level-Permissions)\nfor more information on role-based permissions in Affinity.\n\nCurrently, we support one API key per user in your Affinity account. Your API key is able to read\ndata and perform actions in Affinity on your behalf, so keep it safe as you would a password.\n\nProvide your API key as your bearer authentication token to start making calls to Affinity API v2.\n\n## Permissions\n\n### Overall requirements\n\nYou must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most\nusers in most Affinity accounts with API access have this by default — Contact your Affinity admin\nif you are not able to generate an API key, and see\n[this article](https://support.affinity.co/hc/en-us/articles/360015976732-Account-Level-Permissions)\nfor more information on role-based permissions in Affinity.\n\n### Resource-level permissions\n\nThe Affinity API respects sharing permissions that are set in-product. For example, if a given user\ndoes not have access to a list, note, or interaction in-product, they will not be able to see or\nmodify it via API.\n\n### Endpoint-level permissions\n\nMany API endpoints also require endpoint-specific permissions that map to permissions in-product.\nThese permissions, along with the \"Generate an API key\" permission, are managed by your Affinity\nadmin in the Settings page:\n\n| API v2 Endpoint | Required Permission |\n| ---------------------------------------------------------- | ------------------------------------ |\n| GET `/v2/companies` | \"Export All Organizations directory\" |\n| GET `/v2/companies/{id}` | \"Export All Organizations directory\" |\n| GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" |\n| GET `/v2/persons` | \"Export All People directory\" |\n| GET `/v2/persons/{id}` | \"Export All People directory\" |\n| GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" |\n| GET `/v2/opportunities` | \"Export data from Lists\" |\n| GET `/v2/opportunities/{id}` | \"Export data from Lists\" |\n| GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" |\n| GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" |\n\n## Rate Limits\n\nThe Affinity API sets a limit on the number of calls that a user can make per minute, and that all\nthe users on an account can make per month. It also sets a reasonable limit on the number of\nconcurrent requests it will support from an account at one time.\n\nRequests to **both** Affinity API versions will count toward the one pool of requests allowed for a\nuser or account. Once a per-minute, monthly, or concurrent rate limit is hit, subsequent requests\nwill return an error code of 429. **We highly recommend designing your application to handle 429\nerrors.**\n\n### Per-Minute Limits (User-Level)\n\nTo help protect our systems, API requests will be halted at **900 per user, per minute.** We may\nalso lower this limit on a temporary basis to manage API availability.\n\n### Concurrent Request Limits (Account-Level)\n\nTo protect our systems and manage availability across customers, we set a reasonable limit on\nconcurrent requests at the account level. Customers should not expect to hit this limit unless they\nare hitting the API with heavy operations from many concurrent threads at once.\n\n### Monthly Plan Tier Limits (Account-Level)\n\nThe overall number of requests you can make per month will depend on your account's plan tier.\n**This monthly account-level limit resets at the end of each calendar month.** Current rate limits\nby plan tier are:\n\n| Plan Tier | Calls Per Month |\n| ---------- | --------------- |\n| Essentials | None |\n| Scale | 100k |\n| Advanced | 100k |\n| Enterprise | Unlimited\\* |\n\n\\*Per-Minute and Concurrent Request Limits still apply.\n\n### Rate Limit Headers\n\nAll API calls will return the following response headers with information about per-minute and\nmonthly limits:\n\n| Header | Description |\n| -------------------------------- | ------------------------------------------------------- |\n| X-Ratelimit-Limit-User | Number of requests allowed per minute for the user |\n| X-Ratelimit-Limit-User-Remaining | Number of requests remaining for the user |\n| X-Ratelimit-Limit-User-Reset | Time in seconds before the limit resets for the user |\n| X-Ratelimit-Limit-Org | Number of requests allowed per month for the account |\n| X-Ratelimit-Limit-Org-Remaining | Number of requests remaining for the account |\n| X-Ratelimit-Limit-Org-Reset | Time in seconds before the limit resets for the account |\n\n## Pagination\n\nWhen an endpoint is expected to return multiple results, we break the results up into pages to make\nthem easier to handle. To cycle forward through multiple pages of data, look for the `nextUrl`\nproperty in the `pagination` portion of an API response, and use it for your next request. See\nendpoint documentation for more information.\n\n## Error Codes\n\nHere is a list of the error codes this API will generally return if something goes wrong (see\nendpoint documentation for endpoint-specific error information):\n\n| Error Code | Meaning |\n| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 400 | Bad Request — See endpoint documentation for more information. |\n| 401 | Unauthorized — Your API key is invalid. |\n| 403 | Forbidden — Insufficient rights to a resource. |\n| 404 | Not Found — Requested resource does not exist. See endpoint documentation for more information. |\n| 405 | Method Not Allowed — The method being used is not supported for this resource. |\n| 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. |\n| 429 | Too Many Requests — You have exceeded the rate limit. |\n| 500 | Internal Server Error — We had a problem with our server. Try again later. |\n| 503 | Service Unavailable — This shouldn't generally happen. Contact us if you encounter this error. |\n\n# Data Model\n\n## The Basics\n\n- The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please\n note: Companies are called Organizations in the Affinity web app.) These have profiles in the\n Affinity web app and can be added to Lists.\n- A lot of the work of Affinity happens within Lists. A **List** is a spreadsheet-like collection of\n rows tied to Persons, Companies, or Opportunities.\n- Each row on a List is a **List Entry**. A List Entry contains data and metadata about a given\n Person, Company, or Opportunity in the context of a List. This includes list-specific field\ndata,\n and information about who added the row to the List and when.\n - Do note that a given entity can be added to a List more than once, i.e., it can have\nmultiple\n List Entries on the same List. These List Entries can have different list-specific field\ndata\n and List Entry-level metadata.\n- Each column on a List maps to a **Field**. Fields and field data also show up within Affinity\n profile pages, extensions, and integrations.\n - Some Fields are scoped to a single List — These are **list-specific fields**, and in the\nAPI,\n their data can only be accessed through the List Entry resource. \"Global\" data from other\nFields\n can be accessed both through the Person/Company/Opportunity resource and the List Entry\n resource.\n\n## Working with Field Data\n\n### Field Types and IDs\n\nThere are a few types of Fields in Affinity, differentiated by the scope and source of their data:\n\n| Field Type | Description | Example Fields | Field ID Pattern |\n| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| `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`. |\n| `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` |\n| `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` |\n| `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` |\n\n### Field Value Types\n\nField data can take a variety of shapes. These value types are described in the Affinity Help Center\n[here](https://support.affinity.co/hc/en-us/articles/115001608232-How-to-create-a-new-column-in-a-list).\nHere is a list of the same value types, as represented in this API. Notice how array types end with\n`-multi`:\n\n| Single Type | Array Type |\n| ------------------- | ------------------------- |\n| `text` | Not supported in Affinity |\n| `number` | `number-multi` |\n| `datetime` | Not supported in Affinity |\n| `location` | `location-multi` |\n| `dropdown` | `dropdown-multi` |\n| `ranked-dropdown` | Not supported in Affinity |\n| `person` | `person-multi` |\n| `company` | `company-multi` |\n| `filterable-text`\\* | `filterable-text-multi`\\* |\n\n\\*Please note that `filterable-text` and `filterable-text-multi` are special types that operate\nsimilarly to `dropdown` and `dropdown-multi`. They are reserved for Affinity-populated Fields, and\nusers cannot create Fields with these types.\n\nWhen an array-typed value has no data in it, the API will return `null` (rather than an empty\narray).\n\n### Retrieving Field Data\n\nTo retrieve field data on companies, persons, or opportunities, call GET `/v2/companies`, GET\n`/v2/persons`, or one of our GET `*/list-entries` endpoints. (Note that Opportunities only have\nlist-specific Fields, so all their field data will live on the `*/list-entries` endpoints.) For most\nof these endpoints, you will need to specify the Fields for which you want data returned via the\n`fieldIds` or `fieldTypes` parameter — Otherwise, entities will be returned without any field data\nattached.\n\nThe GET `/v2/companies` and `/v2/persons` endpoints can return entities with enriched, global, and\nrelationship intelligence field data attached, but do not support list-specific field data. **To get\ncomprehensive field data including list-specific field data on Companies and Persons, use the GET\n`*/list-entries` endpoints.**\n\n### Specifying Desired Fields (Field Selection)\n\nAs mentioned above, you will need to specify the Fields (either by ID or by Type) for which you want\ndata returned when using the following endpoints:\n\n- GET `/v2/companies`\n- GET `/v2/companies/{id}`\n- GET `/v2/persons`\n- GET `/v2/persons/{id}`\n- GET `/v2/lists/{listId}/list-entries`\n\nEach of these endpoints has a `fieldIds` parameter that accepts an array of Field IDs, and a\n`fieldTypes` parameter that accepts an array of Field Types. Use the GET `*/fields` endpoints to get\nField IDs, Field Types, and other Field-level metadata:\n\n- Call GET `/v2/companies/fields` and `/v2/persons/fields` to get a list of the enriched, global,\n and relationship intelligence (AKA non-list-specific) Fields that exist on Companies and\nPersons,\n respectively. These are the Fields whose values are available to pull via GET `/v2/companies`,\nGET\n `/v2/companies/{id}`, GET `/v2/persons`, and `/v2/persons/{id}`.\n\n- Call GET `/v2/lists/{listId}/fields` to get a list of the enriched, global, relationship\n intelligence, **and list-specific** Fields for a given List. These are the Fields whose values\nare\n available to pull via GET `/v2/lists/{listId}/list-entries`.\n\nThe following endpoints don't require field selection:\n\n- GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` — See below. This endpoint returns just\n the field data that has been pulled into the given Saved View via UI.\n- GET `/v2/companies/{id}/list-entries` and GET `/v2/persons/{id}/list-entries` — These endpoints\n return comprehensive field data for the given person or company in the context of each List\nEntry.\n### Saved Views\n\nA Saved View allows a user to configure the Fields they want to see in the UI for a given List, and\nset filters and sorts on the rows on that List. A List can have multiple Saved Views. In the context\nof this API, Saved Views can be useful for specifying the exact Fields for which data is needed. The\n`*/saved-views/{viewId}/list-entries` endpoint also respects the filters that have been set on the\ngiven Saved View in the Affinity web app. (It does not, however, respect sorts just yet.)\n\n### Partner Data Restrictions\n\nThis API supports pulling data from\n[Affinity Data](https://support.affinity.co/hc/en-us/articles/360058255052-Affinity-Data) fields and\nselect\n[Dealroom fields](https://support.affinity.co/hc/en-us/articles/6106558518797-Dealroom-co-data-in-Affinity#h_01G2N22SVH7TJR3DJV3NQDE9HQ).\nDue the agreements we have with some of our data partners, the API does not expose data from the\nfollowing sources:\n\n- Crunchbase, including Crunchbase UUID\n- Pitchbook\n- [Dealroom \"exclusive\" fields](https://support.affinity.co/hc/en-us/articles/6106558518797-Dealroom-co-data-in-Affinity#h_01G2N22YEAZJ5TC1X9ENKZFWF5)\n\n## A Note on Nested Associations\n\nSome GET endpoints return \"association\" data under `fields`. For example, the Persons GET endpoints\nreturn data about which Companies a Person is associated with in Affinity. The Opportunities GET\nendpoints return similar data about associated Companies and Persons. The List Entries GET endpoints\nalso return this data for Person and Opportunity List Entries.\n\nThe API truncates these nested arrays of Persons or Companies **at 100 entries**. For example, if an\nOpportunity is associated with 200 Persons in Affinity, only 100 of those Persons will be returned\nby the GET `/opportunities` or `/opportunities/{id}` endpoint.\n\n# User Guides\n\n## A Tour of Our GET Endpoints\n\n| Desired Data | Relevant Endpoints | Notes |\n| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |\n| Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List |\n| Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View |\n| Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned |\n| All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | |\n| Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` |\n| Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | |\n| Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | |\n\nTip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its\nAffinity web app URL.\n\n# Changelog\n## February 28th, 2024\n- Added the following endpoints in BETA:\n|Method|URL|Summary|\n|--|--|--|\n|GET|`/v2/lists/{listId}/list-entries/{listEntryId}`|Get a single List Entry on a List|\n|GET|`/v2/lists/{listId}/list-entries/{listEntryId}/fields`|Get field values on a single List Entry|\n|PATCH|`/v2/lists/{listId}/list-entries/{listEntryId}/fields`|Perform batch operations on a list entry's fields|\n|GET|`/v2/lists/{listId}/list-entries/{listEntryId}/fields/{fieldId}`|Get a single field value|\n|POST|`/v2/lists/{listId}/list-entries/{listEntryId}/fields/{fieldId}`|Update a single field value on a List Entry|\n\n## January 17th, 2024\n- Document `X-Ratelimit` headers in the schema for all endpoints.\n## January 15th, 2024\n- Add default responses to all endpoints to document all possible error codes that can be returned by the API.\n- Updated 400 error responses to correctly include the `bad-request` error code as a possible error.\n## December 3rd, 2024\n- Properly document `listId` property on `CompanyListEntry`, `PersonListEntry`, and\n `OpportunityListEntry` schemas.\n\n## September 25th, 2024\n- Upgrade schema to Openapi 3.1\n## August 5, 2024\n- Correct `opp` to `opportunity` to match documentation for the `List` `type` property.\n## July 24, 2024\n- More accurate documentation for response properties that are enums — Enums with `null` as a\n possible value will have it listed as one.\n\n## March 25, 2024\n- Added the ability to retrieve the date and other details of your firm's \"First Email\", \"Last\n Email\", \"First Event\", \"Last Event\", \"Next Event\", \"First Chat Message\", \"Last Chat Message\",\nand\n \"Last Contact\" with a given entity. Use these timestamps to add relationship context to your\n applications, and to identify founders and companies that need investors' attention.\n- Endpoints that previously required a `fieldIds` parameter to return field data, now accept either\n `fieldIds` or `fieldTypes`, and will return field data accordingly. See the\n [Specifying Desired Fields (Field Selection)](#section/Data-Model/Working-with-Field-Data)\nsection\n of these docs for more information. The new `fieldTypes` parameter should make field data\n retrieval easier for users looking to pull data from many similar Fields at a time.\n\n## January 4, 2023\n- Most endpoints that return field data now require the user to use the `fieldIds` parameter to\n specify which Fields they want data for. Without `fieldIds` specified, these endpoints will\nreturn\n basic entity data but not field data.\n\n## December 12, 2023\n- Added the ability to retrieve metadata (e.g. ID, name, type, enrichment source, and data type) on\n Fields. See the [Retrieving Field Metadata](#section/Data-Model/Working-with-Field-Data)\nsection\n of these docs for more information.\n", + "description": "# Introduction\n\nWelcome to Affinity API v2! This API provides a RESTful interface for building internal apps,\nautomated workflows, 3rd party integrations, and for connecting Affinity to the rest of your tech\nstack.\n\nThe legacy Affinity v1 API can be found at [api-docs.affinity.co](https://api-docs.affinity.co/).\nThe v2 API is not at feature parity with v1 - we are continuing to develop new v2 APIs to support\nall v1 functionality over time.\n\n**The Affinity APIs are only available on select license types.** See\n[this Help Center article](https://support.affinity.co/hc/en-us/articles/5563700459533-Getting-started-with-the-Affinity-API-FAQs)\nor contact your Customer Success Manager for more information.\n\n# Getting Started\n\nAll Affinity API endpoints use the base URL `https://api.affinity.co`. All v2 endpoint paths start\nwith `/v2`. Requests must be sent over HTTPS.\n\nThe first few sections of these docs cover general information on the API. Each subsequent section\ncovers a set of API endpoints.\n\nEach endpoint is documented with its accepted request parameters, expected response shapes, and a\nsample request and response. The shape of a given response can vary depending on what \"type\" of\nobject or data is being returned. When this is the case, the response documentation will include a\ndropdown that can be used to select the \"type\" for which to display the response shape.\n\n## Authentication\n\nAffinity API v2 uses API keys and **bearer authentication** (this is an important difference from\nAffinity API v1's use of basic authentication).\n\nTo generate an API key, navigate to the Settings page in the Affinity web app. You will need the\n\"Generate an API key\" role-based permission controlled by your Affinity admin. See\n[this Help Center article](https://support.affinity.co/hc/en-us/articles/360032633992-How-to-obtain-your-API-Key)\nfor full instructions on API key generation, and\n[this article](https://support.affinity.co/hc/en-us/articles/360015976732-Account-Level-Permissions)\nfor more information on role-based permissions in Affinity.\n\nProvide your API key as your bearer authentication token to start making calls to Affinity API v2.\n\nWe support one API key per user in your Affinity account. Your API key is able to read data and\nperform actions in Affinity on your behalf, so keep it safe as you would a password.\n\n## Permissions\n\n### Overall Requirements\n\nYou must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most\nusers in Affinity have this by default — Contact your Affinity admin if you are not able to generate\nan API key, and see\n[this article](https://support.affinity.co/hc/en-us/articles/360015976732-Account-Level-Permissions)\nfor more information on role-based permissions in Affinity.\n\n### Resource-Level Permissions\n\nThe Affinity API respects sharing permissions that are set in-product. For example, if a given user\ndoes not have access to a list, note, or interaction in-product, they will not be able to see or\nmodify it via API.\n\n### Endpoint-Level Permissions\n\nMany API endpoints require endpoint-specific permissions in-product. These permissions, along with\nthe \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page. In\nthe description of each endpoint you will see the required permissions needed.\n\n## Rate Limits\n\nThe Affinity API sets a limit on the number of calls that a user can make per minute, and that all\nthe users on an account can make per month. It also sets a reasonable limit on the number of\nconcurrent requests it will support from an account at one time.\n\nRequests to **both** Affinity API versions will count toward the one pool of requests allowed for a\nuser or account. Once a per-minute, monthly, or concurrent rate limit is hit, subsequent requests\nwill return an error code of 429. **We highly recommend designing your application to handle 429\nerrors.**\n\n### Per-Minute Limits (User-Level)\n\nTo help protect our systems, API requests will be halted at **900 per user, per minute.** We may\nalso lower this limit on a temporary basis to manage API availability.\n\n### Concurrent Request Limits (Account-Level)\n\nTo protect our systems and manage availability across customers, we set a reasonable limit on\nconcurrent requests at the account level. Customers should not expect to hit this limit unless they\nare hitting the API with heavy operations from many concurrent threads at once.\n\n### Monthly Plan Tier Limits (Account-Level)\n\nThe overall number of requests you can make per month will depend on your account's plan tier.\n**This monthly account-level limit resets at the end of each calendar month.** Current rate limits\nby plan tier are:\n\n| Plan Tier | Calls Per Month |\n| ---------- | --------------- |\n| Essentials | None |\n| Scale | 100k |\n| Advanced | 100k |\n| Enterprise | Unlimited\\* |\n\n\\*Per-Minute and Concurrent Request Limits still apply.\n\n### Rate Limit Headers\n\nAll API calls will return the following response headers with information about per-minute and\nmonthly limits:\n\n| Header | Description |\n| -------------------------------- | ------------------------------------------------------- |\n| X-Ratelimit-Limit-User | Number of requests allowed per minute for the user |\n| X-Ratelimit-Limit-User-Remaining | Number of requests remaining for the user |\n| X-Ratelimit-Limit-User-Reset | Time in seconds before the limit resets for the user |\n| X-Ratelimit-Limit-Org | Number of requests allowed per month for the account |\n| X-Ratelimit-Limit-Org-Remaining | Number of requests remaining for the account |\n| X-Ratelimit-Limit-Org-Reset | Time in seconds before the limit resets for the account |\n\n## Pagination\n\nWhen an endpoint is expected to return multiple results, we break the results into pages to make\nthem easier to handle. To cycle forward through multiple pages of data, look for the `nextUrl`\nproperty in the `pagination` portion of an API response, and use it for your next request. See\nendpoint documentation for more information.\n\n## Filtering\n\nSome endpoints support a filtering language for flexible and powerful queries. This allows for the\ncreation of complex filter expressions using different operators and boolean logic in a single\nfilter string. The description of each endpoint will contain information on which filter properties\nand operators are supported.\n\n### Rules\n\n- Spaces are insignificant by default. For example, `field = hello` and `field=hello` are both\n valid.\n- If spaces are significant, they need to be inside double quotes, for example,\n `field = \"hello world\"`\n- Special characters need to be escaped with a backslash: `field=\"hello\\\" world\"`
Full list of\n special characters: `\\ * ~ ! & = > < $ ^ | \" ' ( ) ] [ /`\n- Use `&` and `|` for boolean operations: `foo = 1 | baz = 2 & bar = 3`. Boolean Algebra Logic is\n assumed: `&` takes precedence over `|`. When evaluating the condition above, `baz = 2 & bar = 3`\n will be computed first, and then the result will be `or`'ed with `foo=1`\n- Parentheses can be used to specify the order of operations. In the example above, to make sure\n that `foo = 1 | baz = 2` is evaluated first, parentheses must be placed\n `(foo = 1 | baz = 2) & bar = 3`\n\n### Grammar\n\n#### Simple Types\n\n| Definition | Property Type | Operator | Example |\n| ------------------------ | ---------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------- |\n| exact match | all | = | content = “hello world”
content=hello |\n| starts with | text | =^ | content =^ he |\n| ends with | text | =$ | content =$ llo |\n| contains | text | =~ | content =~ lo |\n| greater than | int32, int64, float, double, decimal, date, datetime | \\> | count > 1 |\n| greater than or equal to | int32, int64, float, double, decimal, date, datetime | \\>= | content >= 1 |\n| less than | int32, int64, float, double, decimal, date, datetime | \\< | count < 1 |\n| less than or equal to | int32, int64, float, double, decimal, date, datetime | \\<= | content <= 1 |\n| is NULL | all | != \\* | content != \\* |\n| is not NULL | all | =\\* | content = \\* |\n| is empty | text | =\"\" | content = \"\" |\n| negation | all | ! | content != ”hello world”
!(content = ”hello world”)
!(content =^ “hello world”) |\n\n#### Collections (all types)\n\n| Definition | Operator | Example |\n| ------------------------- | -------- | ------------------------------------ |\n| exact match with ordering | = | industries = [Healthcare,Fintech] |\n| contains all | =~ | industries =~ [Healthcare,Fintech] |\n| empty | =[] | industries =[] |\n| negation | ! | !(industries = [Healthcare,Fintech]) |\n\n## Error Codes\n\nHere is a list of the error codes the API will return if something goes wrong (see endpoint\ndocumentation for endpoint-specific errors):\n\n| Error Code | Meaning |\n| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 400 | Bad Request — See endpoint documentation for more information. |\n| 401 | Unauthorized — Your API key is invalid. |\n| 403 | Forbidden — Insufficient rights to a resource. |\n| 404 | Not Found — Requested resource does not exist. See endpoint documentation for more information. |\n| 405 | Method Not Allowed — The method being used is not supported for this resource. |\n| 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. |\n| 429 | Too Many Requests — You have exceeded the rate limit. |\n| 500 | Internal Server Error — We had a problem with our server. Try again later. |\n| 503 | Service Unavailable — This shouldn't generally happen. Contact us if you encounter this error. |\n\n## Beta Endpoints\n\nYou’ll notice in our documentation that some endpoints will be marked as BETA. These endpoints are\nnewly released and will eventually progress to General Availability (GA). While an endpoint is in\nBETA there are some important things to consider:\n\n- The development of this endpoint may still be in progress. This means new capabilities, request\n parameters, response data, and performance improvements may be adjusted over time. Because of\n this, breaking changes may occur to the endpoint WITHOUT notice or versioning.\n- As this is an early release, bug fixes may still be ongoing as well, and we encourage you to\n report bugs to [support@affinity.co](mailto:support@affinity.co).\n- In addition, your feedback around the capabilities of the endpoint are highly valuable, please\n reach out to your CSM to provide feedback to our product team.\n\n# Data Model\n\n## The Basics\n\nThe three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Note:\nCompanies are called Organizations in the Affinity web app.) These have profiles in the Affinity web\napp and can be added to Lists.\n\nA **List** is a spreadsheet-like collection of rows tied to Persons, Companies, or Opportunities.\n\n- Each row on a List is a **List Entry**. A List Entry contains data and metadata about a given\n Person, Company, or Opportunity in the context of a List. This includes list-specific field data,\n and information about who added the row to the List and when.\n- A given entity can be added to a List more than once. These List Entries can have different\n List-specific field data and List Entry-level metadata.\n\nEach column on a List maps to a **Field**. Fields show up within Affinity profile pages, extensions,\nand integrations. There are two categories of fields:\n\n- **List-specific fields** are scoped to a single List. In the API, their data can only be accessed\n through the List Entry resource.\n- **Global fields** belong to entities directly. These can include default fields, fields created by\n you, enrichment fields, or relationship intelligence fields. They can be accessed through the\n Person/Company/Opportunity resources and the List Entry resource.\n\n## Working with Field Data\n\n### Field Types and IDs\n\nHere is a deeper look at the types of Fields in Affinity, differentiated by the scope and source of\ntheir data:\n\n| Field Type | Description | Example Fields | Field ID Pattern |\n| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| `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`. |\n| `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` |\n| `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` |\n| `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` |\n\n### Field Value Types\n\nField data can take a variety of shapes. These value types are described in the Affinity Help Center\n[creating columns in lists](https://support.affinity.co/hc/en-us/articles/115001608232-How-to-create-a-new-column-in-a-list).\nHere is a list of the same value types, as represented in this API. Notice how array types end with\n`-multi`:\n\n| Single Type | Array Type |\n| ------------------- | ------------------------- |\n| `text` | Not supported in Affinity |\n| `number` | `number-multi` |\n| `datetime` | Not supported in Affinity |\n| `location` | `location-multi` |\n| `dropdown` | `dropdown-multi` |\n| `ranked-dropdown` | Not supported in Affinity |\n| `person` | `person-multi` |\n| `company` | `company-multi` |\n| `filterable-text`\\* | `filterable-text-multi`\\* |\n\n\\*Note that `filterable-text` and `filterable-text-multi` are special types that operate similarly\nto `dropdown` and `dropdown-multi`. They are reserved for Affinity-populated Fields, and users\ncannot create Fields with these types.\n\nWhen an array-typed value has no data in it, the API will return `null` (rather than an empty\narray).\n\n### Retrieving Field Data\n\nTo retrieve field data on companies, persons, or opportunities, call GET `/v2/companies`, GET\n`/v2/persons`, or one of our GET `*/list-entries` endpoints. (Note that Opportunities only have\nlist-specific Fields, so all their field data will live on the `*/list-entries` endpoints.) For most\nof these endpoints, you will need to specify the Fields for which you want data returned via the\n`fieldIds` or `fieldTypes` parameter — Otherwise, entities will be returned without any field data\nattached.\n\nThe GET `/v2/companies` and `/v2/persons` endpoints can return entities with enriched, global, and\nrelationship intelligence field data attached, but do not support list-specific field data. **To get\ncomprehensive field data including list-specific field data on Companies and Persons, use the GET\n`*/list-entries` endpoints.**\n\n### Specifying Desired Fields (Field Selection)\n\nAs mentioned above, you will need to specify the Fields (either by ID or by Type) for which you want\ndata returned when using the following endpoints:\n\n- GET `/v2/companies`\n- GET `/v2/companies/{id}`\n- GET `/v2/persons`\n- GET `/v2/persons/{id}`\n- GET `/v2/lists/{listId}/list-entries`\n\nEach of these endpoints has a `fieldIds` parameter that accepts an array of Field IDs, and a\n`fieldTypes` parameter that accepts an array of Field Types. Use the GET `*/fields` endpoints to get\nField IDs, Field Types, and other Field-level metadata:\n\n- Call GET `/v2/companies/fields` and `/v2/persons/fields` to get a list of the enriched, global,\n and relationship intelligence (AKA non-list-specific) Fields that exist on Companies and Persons,\n respectively. These are the Fields whose values are available to pull via GET `/v2/companies`, GET\n `/v2/companies/{id}`, GET `/v2/persons`, and `/v2/persons/{id}`.\n- Call GET `/v2/lists/{listId}/fields` to get a list of the enriched, global, relationship\n intelligence, **and list-specific** Fields for a given List. These are the Fields whose values are\n available to pull via GET `/v2/lists/{listId}/list-entries`.\n\nThe following endpoints don't require field selection:\n\n- GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` — See below. This endpoint returns just\n the field data that has been pulled into the given Saved View via UI.\n- GET `/v2/companies/{id}/list-entries` and GET `/v2/persons/{id}/list-entries` — These endpoints\n return comprehensive field data for the given person or company in the context of each List Entry.\n\n### Saved Views\n\nA Saved View allows a user to configure the Fields they want to see in the UI for a given List, and\nset filters and sorts on the rows on that List. A List can have multiple Saved Views. In the context\nof this API, Saved Views can be useful for specifying the exact Fields for which data is needed. The\n`*/saved-views/{viewId}/list-entries` endpoint also respects the filters that have been set on the\ngiven Saved View in the Affinity web app. (It does not, however, respect sorts just yet.)\n\n### Partner Data Restrictions\n\nThis API supports pulling data from\n[Affinity Data](https://support.affinity.co/hc/en-us/articles/360058255052-Affinity-Data) fields and\nselect\n[Dealroom fields](https://support.affinity.co/hc/en-us/articles/6106558518797-Dealroom-co-data-in-Affinity#h_01G2N22SVH7TJR3DJV3NQDE9HQ).\nDue the agreements we have with some of our data partners, the API does not expose data from the\nfollowing sources:\n\n- Crunchbase, including Crunchbase UUID\n- Pitchbook\n- [Dealroom \"exclusive\" fields](https://support.affinity.co/hc/en-us/articles/6106558518797-Dealroom-co-data-in-Affinity#h_01G2N22YEAZJ5TC1X9ENKZFWF5)\n\n## Nested Associations\n\nSome GET endpoints return \"association\" data under `fields`. For example, the Persons GET endpoints\nreturn data about which Companies a Person is associated with in Affinity. The Opportunities GET\nendpoints return similar data about associated Companies and Persons. The List Entries GET endpoints\nalso return this data for Person and Opportunity List Entries.\n\nThe API truncates these nested arrays of Persons or Companies **at 100 entries**. For example, if an\nOpportunity is associated with 200 Persons in Affinity, only 100 of those Persons will be returned\nby the GET `/opportunities` or `/opportunities/{id}` endpoint.\n\n# User Guides\n\n## A Tour of Our GET Endpoints\n\n| Desired Data | Relevant Endpoints | Notes |\n| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |\n| Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List |\n| Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View |\n| Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned |\n| All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | |\n| Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` |\n| Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | |\n| Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | |\n\nTip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its\nAffinity web app URL.\n\n# Changelog\n\n## September 25th, 2025\n\n- Added the following endpoints in BETA:\n\n| Method | URL | Summary |\n| ------ | ----------------------------------- | ---------------------------- |\n| GET | `/v2/company-merges` | Get All Company Merge status |\n| POST | `/v2/company-merges` | Initiate Company Merge |\n| GET | `/v2/company-merges/{mergeId}` | Get Company Merge status |\n| GET | `/v2/tasks/company-merges` | Get All Company Merge Tasks |\n| GET | `/v2/tasks/company-merges/{taskId}` | Get Company Merge Task |\n\n## July 30th, 2025\n\n- Added the following endpoints in BETA:\n\n| Method | URL | Summary |\n| ------ | ---------------------------------- | --------------------------- |\n| GET | `/v2/person-merges` | Get All Person Merge status |\n| POST | `/v2/person-merges` | Initiate Person Merge |\n| GET | `/v2/person-merges/{mergeId}` | Get Person Merge status |\n| GET | `/v2/tasks/person-merges` | Get All Person Merge Tasks |\n| GET | `/v2/tasks/person-merges/{taskId}` | Get Person Merge Task |\n\n## May 14th, 2025\n\n- Renamed all path parameters named simply \"id\" to a more descriptive name (eg. \"personId\"). This\n will not have any effect on the API at runtime, but may impact code relying on the OpenAPI spec\n doing type generation.\n\n## April 9th, 2025\n\n- The following endpoints are no longer in BETA:\n\n| Method | URL | Summary |\n| ------ | ---------------------------------------------------------------- | ------------------------------------------------- |\n| GET | `/v2/lists/{listId}/list-entries/{listEntryId}` | Get a single List Entry on a List |\n| GET | `/v2/lists/{listId}/list-entries/{listEntryId}/fields` | Get field values on a single List Entry |\n| PATCH | `/v2/lists/{listId}/list-entries/{listEntryId}/fields` | Perform batch operations on a list entry's fields |\n| GET | `/v2/lists/{listId}/list-entries/{listEntryId}/fields/{fieldId}` | Get a single field value |\n| POST | `/v2/lists/{listId}/list-entries/{listEntryId}/fields/{fieldId}` | Update a single field value on a List Entry |\n\n## March 31st, 2025\n\n- The following beta endpoints now support updating association fields.\n\n| Method | URL | Summary |\n| ------ | ---------------------------------------------------------------- | ------------------------------------------------- |\n| PATCH | `/v2/lists/{listId}/list-entries/{listEntryId}/fields` | Perform batch operations on a list entry's fields |\n| POST | `/v2/lists/{listId}/list-entries/{listEntryId}/fields/{fieldId}` | Update a single field value on a List Entry |\n\n## February 28th, 2025\n\n- Added the following endpoints in BETA:\n\n| Method | URL | Summary |\n| ------ | ---------------------------------------------------------------- | ------------------------------------------------- |\n| GET | `/v2/lists/{listId}/list-entries/{listEntryId}` | Get a single List Entry on a List |\n| GET | `/v2/lists/{listId}/list-entries/{listEntryId}/fields` | Get field values on a single List Entry |\n| PATCH | `/v2/lists/{listId}/list-entries/{listEntryId}/fields` | Perform batch operations on a list entry's fields |\n| GET | `/v2/lists/{listId}/list-entries/{listEntryId}/fields/{fieldId}` | Get a single field value |\n| POST | `/v2/lists/{listId}/list-entries/{listEntryId}/fields/{fieldId}` | Update a single field value on a List Entry |\n\n## January 17th, 2025\n\n- Document `X-Ratelimit` headers in the schema for all endpoints.\n\n## January 15th, 2025\n\n- Add default responses to all endpoints to document all possible error codes that can be returned\n by the API.\n- Updated 400 error responses to correctly include the `bad-request` error code as a possible error.\n\n## December 3rd, 2024\n\n- Properly document `listId` property on `CompanyListEntry`, `PersonListEntry`, and\n `OpportunityListEntry` schemas.\n\n## September 25th, 2024\n\n- Upgrade schema to OpenAPI 3.1\n\n## August 5, 2024\n\n- Correct `opp` to `opportunity` to match documentation for the `List` `type` property.\n\n## July 24, 2024\n\n- More accurate documentation for response properties that are enums — Enums with `null` as a\n possible value will have it listed as one.\n\n## March 25, 2024\n\n- Added the ability to retrieve the date and other details of your firm's \"First Email\", \"Last\n Email\", \"First Event\", \"Last Event\", \"Next Event\", \"First Chat Message\", \"Last Chat Message\", and\n \"Last Contact\" with a given entity. Use these timestamps to add relationship context to your\n applications, and to identify founders and companies that need investors' attention.\n- Endpoints that previously required a `fieldIds` parameter to return field data, now accept either\n `fieldIds` or `fieldTypes`, and will return field data accordingly. See the\n [Specifying Desired Fields (Field Selection)](#section/Data-Model/Working-with-Field-Data) section\n of these docs for more information. The new `fieldTypes` parameter should make field data\n retrieval easier for users looking to pull data from many similar Fields at a time.\n\n## January 4, 2023\n\n- Most endpoints that return field data now require the user to use the `fieldIds` parameter to\n specify which Fields they want data for. Without `fieldIds` specified, these endpoints will return\n basic entity data but not field data.\n\n## December 12, 2023\n\n- Added the ability to retrieve metadata (e.g. ID, name, type, enrichment source, and data type) on\n Fields. See the [Retrieving Field Metadata](#section/Data-Model/Working-with-Field-Data) section\n of these docs for more information.\n", "license": { "name": "Proprietary", "url": "https://www.affinity.co/legal/terms-of-use" @@ -34,18 +35,47 @@ "description": "Operations about auths", "name": "auth" }, + { + "description": "Operations about calls", + "name": "calls" + }, + { + "description": "Operations about chat messages", + "name": "chatMessages" + }, { "description": "Operations about companies", "name": "companies" }, + { + "description": "Operations about company merges", + "name": "companyMerges" + }, + { + "description": "Operations about emails", + "name": "emails" + }, { "description": "Operations about lists", "name": "lists" }, + { + "description": "Operations about meetings", + "name": "meetings" + }, + { + "description": "Operations about notes", + "name": "notes", + "x-stability-level": "beta" + }, { "description": "Operations about opportunities", "name": "opportunities" }, + { + "description": "Operations about person merges", + "name": "personMerges" + }, { "description": "Operations about persons", "name": "persons" @@ -54,15 +84,15 @@ "paths": { "/v2/auth/whoami": { "get": { - "description": "Returns metadata about the current user.", + "description": "Returns information about the authenticated user, their current organization, and API key permissions.\nUse this endpoint to verify your authentication and understand your available API access levels.", "summary": "Get current user", - "operationId": "getV2AuthWhoami", + "operationId": "v2_auth_whoami__GET", "tags": [ "auth" ], "responses": { "200": { - "description": "Get current user", + "description": "OK", "content": { "application/json": { "schema": { @@ -100,13 +130,13 @@ } } }, - "/v2/companies": { + "/v2/calls": { "get": { - "description": "Paginate through Companies in Affinity.\nReturns basic information and non-list-specific field data on each Company.\n\nTo retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter\nto specify the Fields for which you want data returned.\nThese Field IDs and Types can be found using the GET `/v2/companies/fields` endpoint.\nWhen no `fieldIds` or `fieldTypes` are provided, Companies will be returned without any field data attached.\nTo supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this:\n`?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`.\n\nRequires the \"Export All Organizations directory\" [permission](#section/Getting-Started/Permissions).", - "summary": "Get all Companies", - "operationId": "getV2Companies", + "description": "Paginate through all calls in Affinity. Returns basic information about the call interaction\nand its participants. Will only return calls that the current authenticated user has \npermission to see.\n\nYou can filter calls using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties.\n| **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** |\n|-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|----------------------------------|\n| `id` | Unique identifier for Calls | `int64` | `=` | `id=1` |\n| `startTime` | Start time of when the Call was held | `datetime` | `>`, `<`, `>=`, `<=` | `sentAt>2025-01-01T01:00:00Z` |\n| `createdAt` | When the Call was created in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-01-01T01:00:00Z` |\n| `updatedAt` | When the Call was updated in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-01-01T01:00:00Z`|\n", + "summary": "Get metadata on all Calls", + "operationId": "v2_calls__GET", "tags": [ - "companies" + "calls" ], "parameters": [ { @@ -118,7 +148,8 @@ "examples": [ "ICAgICAgYmVmb3JlOjo6Nw" ] - } + }, + "example": "ICAgICAgYmVmb3JlOjo6Nw" }, { "name": "limit", @@ -133,92 +164,113 @@ "examples": [ 100 ] - } + }, + "example": 100 }, { - "name": "ids", - "description": "Company IDs", + "name": "filter", + "description": "Filter options", "in": "query", - "style": "form", - "explode": true, "schema": { - "type": "array", - "items": { - "type": "integer", - "format": "int64", - "minimum": 1, - "maximum": 9223372036854776000 + "type": "string" + }, + "example": "id=1234" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/interactions.CallPaged" + } + } + }, + "headers": { + "X-Ratelimit-Limit-User": { + "$ref": "#/components/headers/X-Ratelimit-Limit-User" }, - "examples": [ - [ - 1 - ], - [ - 1, - 2 - ] - ] + "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" + }, + "default": { + "$ref": "#/components/responses/default" + } + } + } + }, + "/v2/chat-messages": { + "get": { + "description": "Paginate through all chat messages in Affinity. Returns basic information about the chat message\ninteraction and its participants. Will only return chat messages that the current authenticated\nuser has permission to see.\n\nYou can filter chat messages using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties.\n| **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** |\n|-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|----------------------------------|\n| `id` | Unique identifier for Chat Messages | `int64` | `=` | `id=1` |\n| `sentAt` | When the Chat Message was sent at | `datetime` | `>`, `<`, `>=`, `<=` | `sentAt>2025-01-01T01:00:00Z` |\n| `createdAt` | When the Chat Message was created in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-01-01T01:00:00Z` |\n| `updatedAt` | When the Chat Message was updated in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-01-01T01:00:00Z`|\n", + "summary": "Get metadata on all Chat Messages", + "operationId": "v2_chat-messages__GET", + "tags": [ + "chatMessages" + ], + "parameters": [ { - "name": "fieldIds", - "description": "Field IDs for which to return field data", + "name": "cursor", + "description": "Cursor for the next or previous page", "in": "query", - "style": "form", - "explode": true, "schema": { - "type": "array", - "items": { - "type": "string", - "format": "string" - }, + "type": "string", "examples": [ - [ - "field-1" - ], - [ - "field-1", - "field-2" - ] + "ICAgICAgYmVmb3JlOjo6Nw" ] - } + }, + "example": "ICAgICAgYmVmb3JlOjo6Nw" }, { - "name": "fieldTypes", - "description": "Field Types for which to return field data", + "name": "limit", + "description": "Number of items to include in the page", "in": "query", - "style": "form", - "explode": true, "schema": { - "type": "array", - "items": { - "type": "string", - "format": "string", - "enum": [ - "enriched", - "global", - "relationship-intelligence" - ] - }, + "type": "integer", + "format": "int32", + "minimum": 1, + "maximum": 100, + "default": 100, "examples": [ - [ - "enriched" - ], - [ - "enriched", - "global" - ] + 100 ] - } + }, + "example": 100 + }, + { + "name": "filter", + "description": "Filter options", + "in": "query", + "schema": { + "type": "string" + }, + "example": "id=1234" } ], "responses": { "200": { - "description": "Get all Companies", + "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CompanyPaged" + "$ref": "#/components/schemas/interactions.ChatMessagePaged" } } }, @@ -246,35 +298,68 @@ "400": { "$ref": "#/components/responses/400" }, - "403": { - "$ref": "#/components/responses/403" - }, "default": { "$ref": "#/components/responses/default" } } } }, - "/v2/companies/{id}": { + "/v2/companies": { "get": { - "description": "Returns basic information and non-list-specific field data on the requested Company.\n\nTo retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter\nto specify the Fields for which you want data returned.\nThese Field IDs and Types can be found using the GET `/v2/companies/fields` endpoint.\nWhen no `fieldIds` or `fieldTypes` are provided, Companies will be returned without any field data attached.\nTo supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this:\n`?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`.\n\nRequires the \"Export All Organizations directory\" [permission](#section/Getting-Started/Permissions).", - "summary": "Get a single Company", - "operationId": "getV2CompaniesId", + "description": "Paginate through Companies in Affinity.\nReturns basic information and non-list-specific field data on each Company.\n\nTo retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter\nto specify the Fields for which you want data returned.\nThese Field IDs and Types can be found using the GET `/v2/companies/fields` endpoint.\nWhen no `fieldIds` or `fieldTypes` are provided, Companies will be returned without any field data attached.\nTo supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this:\n`?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`.\n\nRequires the \"Export All Organizations directory\" [permission](#section/Getting-Started/Permissions).", + "summary": "Get all Companies", + "operationId": "v2_companies__GET", "tags": [ "companies" ], "parameters": [ { - "name": "id", - "description": "Company ID", - "in": "path", - "required": true, + "name": "cursor", + "description": "Cursor for the next or previous page", + "in": "query", + "schema": { + "type": "string", + "examples": [ + "ICAgICAgYmVmb3JlOjo6Nw" + ] + }, + "example": "ICAgICAgYmVmb3JlOjo6Nw" + }, + { + "name": "limit", + "description": "Number of items to include in the page", + "in": "query", "schema": { "type": "integer", - "format": "int64", + "format": "int32", "minimum": 1, - "maximum": 9223372036854776000 - } + "maximum": 100, + "default": 100, + "examples": [ + 100 + ] + }, + "example": 100 + }, + { + "name": "ids", + "description": "Company IDs", + "in": "query", + "style": "form", + "explode": true, + "schema": { + "type": "array", + "items": { + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9223372036854776000 + } + }, + "example": [ + 1, + 2 + ] }, { "name": "fieldIds", @@ -285,10 +370,18 @@ "schema": { "type": "array", "items": { - "type": "string", - "format": "string" - } - } + "type": "string" + }, + "examples": [ + [ + "field-1" + ] + ] + }, + "example": [ + "field-1", + "field-2" + ] }, { "name": "fieldTypes", @@ -300,23 +393,26 @@ "type": "array", "items": { "type": "string", - "format": "string", "enum": [ "enriched", "global", "relationship-intelligence" ] } - } + }, + "example": [ + "enriched", + "global" + ] } ], "responses": { "200": { - "description": "Get a single Company", + "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Company" + "$ref": "#/components/schemas/CompanyPaged" } } }, @@ -347,9 +443,6 @@ "403": { "$ref": "#/components/responses/403" }, - "404": { - "$ref": "#/components/responses/404" - }, "default": { "$ref": "#/components/responses/default" } @@ -360,7 +453,7 @@ "get": { "description": "Returns metadata on non-list-specific Company Fields.\n\nUse the returned Field IDs to request field data from the GET `/v2/companies` and GET `/v2/companies/{id}` endpoints.", "summary": "Get metadata on Company Fields", - "operationId": "getV2CompaniesFields", + "operationId": "v2_companies_fields__GET", "tags": [ "companies" ], @@ -370,8 +463,12 @@ "description": "Cursor for the next or previous page", "in": "query", "schema": { - "type": "string" - } + "type": "string", + "examples": [ + "ICAgICAgYmVmb3JlOjo6Nw" + ] + }, + "example": "ICAgICAgYmVmb3JlOjo6Nw" }, { "name": "limit", @@ -382,13 +479,17 @@ "format": "int32", "minimum": 1, "maximum": 100, - "default": 100 - } + "default": 100, + "examples": [ + 100 + ] + }, + "example": 100 } ], "responses": { "200": { - "description": "Get metadata on Company Fields", + "description": "OK", "content": { "application/json": { "schema": { @@ -426,17 +527,17 @@ } } }, - "/v2/companies/{id}/lists": { + "/v2/companies/{companyId}": { "get": { - "description": "Returns metadata for all the Lists on which the given Company appears.", - "summary": "Get a Company's Lists", - "operationId": "getV2CompaniesIdLists", + "description": "Returns basic information and non-list-specific field data on the requested Company.\n\nTo retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter\nto specify the Fields for which you want data returned.\nThese Field IDs and Types can be found using the GET `/v2/companies/fields` endpoint.\nWhen no `fieldIds` or `fieldTypes` are provided, Companies will be returned without any field data attached.\nTo supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this:\n`?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`.\n\nRequires the \"Export All Organizations directory\" [permission](#section/Getting-Started/Permissions).", + "summary": "Get a single Company", + "operationId": "v2_companies_companyId__GET", "tags": [ "companies" ], "parameters": [ { - "name": "id", + "name": "companyId", "description": "Company ID", "in": "path", "required": true, @@ -448,33 +549,57 @@ } }, { - "name": "cursor", - "description": "Cursor for the next or previous page", + "name": "fieldIds", + "description": "Field IDs for which to return field data", "in": "query", + "style": "form", + "explode": true, "schema": { - "type": "string" - } + "type": "array", + "items": { + "type": "string" + }, + "examples": [ + [ + "field-1" + ] + ] + }, + "example": [ + "field-1", + "field-2" + ] }, { - "name": "limit", - "description": "Number of items to include in the page", + "name": "fieldTypes", + "description": "Field Types for which to return field data", "in": "query", + "style": "form", + "explode": true, "schema": { - "type": "integer", - "format": "int32", - "minimum": 1, - "maximum": 100, - "default": 100 - } + "type": "array", + "items": { + "type": "string", + "enum": [ + "enriched", + "global", + "relationship-intelligence" + ] + } + }, + "example": [ + "enriched", + "global" + ] } ], "responses": { "200": { - "description": "Get a Company's Lists", + "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ListPaged" + "$ref": "#/components/schemas/Company" } } }, @@ -502,6 +627,9 @@ "400": { "$ref": "#/components/responses/400" }, + "403": { + "$ref": "#/components/responses/403" + }, "404": { "$ref": "#/components/responses/404" }, @@ -511,17 +639,17 @@ } } }, - "/v2/companies/{id}/list-entries": { + "/v2/companies/{companyId}/list-entries": { "get": { "description": "Paginate through the List Entries (AKA rows) for the given Company across all Lists.\nEach List Entry includes field data for the Company, including list-specific field data.\nEach List Entry also includes metadata about its creation, i.e., when it was added to the List and by whom.\n\nRequires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions).", "summary": "Get a Company's List Entries", - "operationId": "getV2CompaniesIdListEntries", + "operationId": "v2_companies_companyId_list-entries__GET", "tags": [ "companies" ], "parameters": [ { - "name": "id", + "name": "companyId", "description": "Company ID", "in": "path", "required": true, @@ -537,8 +665,12 @@ "description": "Cursor for the next or previous page", "in": "query", "schema": { - "type": "string" - } + "type": "string", + "examples": [ + "ICAgICAgYmVmb3JlOjo6Nw" + ] + }, + "example": "ICAgICAgYmVmb3JlOjo6Nw" }, { "name": "limit", @@ -549,13 +681,17 @@ "format": "int32", "minimum": 1, "maximum": 100, - "default": 100 - } + "default": 100, + "examples": [ + 100 + ] + }, + "example": 100 } ], "responses": { "200": { - "description": "Get a Company's List Entries", + "description": "OK", "content": { "application/json": { "schema": { @@ -599,22 +735,38 @@ } } }, - "/v2/lists": { + "/v2/companies/{companyId}/lists": { "get": { - "description": "Returns metadata on Lists.", - "summary": "Get metadata on all Lists", - "operationId": "v2_lists__GET", + "description": "Paginate through all Lists where the given Company appears as an entry and that you have access to view.\nReturns basic List information for each List that contains this Company.", + "summary": "Get a Company's Lists", + "operationId": "v2_companies_companyId_lists__GET", "tags": [ - "lists" + "companies" ], "parameters": [ + { + "name": "companyId", + "description": "Company ID", + "in": "path", + "required": true, + "schema": { + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9223372036854776000 + } + }, { "name": "cursor", "description": "Cursor for the next or previous page", "in": "query", "schema": { - "type": "string" - } + "type": "string", + "examples": [ + "ICAgICAgYmVmb3JlOjo6Nw" + ] + }, + "example": "ICAgICAgYmVmb3JlOjo6Nw" }, { "name": "limit", @@ -625,22 +777,21 @@ "format": "int32", "minimum": 1, "maximum": 100, - "default": 100 - } + "default": 100, + "examples": [ + 100 + ] + }, + "example": 100 } ], "responses": { "200": { - "description": "Get metadata on all Lists", + "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ListWithTypePaged" - }, - "examples": { - "success": { - "$ref": "#/components/examples/success" - } + "$ref": "#/components/schemas/ListPaged" } } }, @@ -668,24 +819,28 @@ "400": { "$ref": "#/components/responses/400" }, + "404": { + "$ref": "#/components/responses/404" + }, "default": { "$ref": "#/components/responses/default" } } } }, - "/v2/lists/{listId}": { + "/v2/companies/{companyId}/notes": { "get": { - "description": "Returns metadata on a single List.", - "summary": "Get metadata on a single List", - "operationId": "v2_lists_listId__GET", + "x-stability-level": "beta", + "description": "| ⚠️ This endpoint is currently in BETA |\n|--|\n\nReturns relevant notes for a given company which includes directly attached notes and notes attached to persons on this company.\n\nYou can filter notes using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties.\n| **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** |\n|-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|---------------------------------|\n| `creator.id` | Filter notes by the creator of the note | `int32` | `=` | `creator.id=1` |\n| `createdAt` | Filter notes by when it was created | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-02-04T10:48:24Z` |\n| `updatedAt` | Filter notes by when it was updated | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-02-03T10:48:24Z`|\n", + "summary": "Get Notes for a Company", + "operationId": "v2_companies_companyId_notes__GET", "tags": [ - "lists" + "companies" ], "parameters": [ { - "name": "listId", - "description": "List ID", + "name": "companyId", + "description": "Company's ID", "in": "path", "required": true, "schema": { @@ -694,26 +849,52 @@ "minimum": 1, "maximum": 9223372036854776000 } + }, + { + "name": "filter", + "description": "Filter options", + "in": "query", + "schema": { + "type": "string" + } + }, + { + "name": "cursor", + "description": "Cursor for the next or previous page", + "in": "query", + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "description": "Number of items to include in the page", + "in": "query", + "schema": { + "type": "integer", + "format": "int32", + "minimum": 0, + "maximum": 100, + "default": 20 + } + }, + { + "name": "totalCount", + "description": "Include total count of the collection in the pagination response", + "in": "query", + "schema": { + "type": "boolean", + "default": false + } } ], "responses": { "200": { - "description": "Get metadata on a single List", + "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ListWithType" - }, - "examples": { - "company-list": { - "$ref": "#/components/examples/company-list" - }, - "opportunity-list": { - "$ref": "#/components/examples/opportunity-list" - }, - "person-list": { - "$ref": "#/components/examples/person-list" - } + "$ref": "#/components/schemas/notes.NotesPaged" } } }, @@ -750,34 +931,23 @@ } } }, - "/v2/lists/{listId}/list-entries": { + "/v2/company-merges": { "get": { - "description": "Paginate through the List Entries (AKA rows) on a given List.\nReturns basic information and field data, including list-specific\nfield data, on each Company, Person, or Opportunity on the List.\nList Entries also include metadata about their creation,\ni.e., when they were added to the List and by whom.\n\nTo retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter\nto specify the Fields for which you want data returned.\nThese Field IDs and Types can be found using the GET `/v2/lists/{listId}/fields` endpoint.\nWhen no `fieldIds` or `fieldTypes` are provided, List Entries will be returned without any field data attached.\nTo supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this:\n`?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`.\n\nRequires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions).", - "summary": "Get all List Entries on a List", - "operationId": "v2_lists_listId_list-entries__GET", + "description": "Retrieve paginated company merges for the organization.\n\n\nReturns all company merges initiated by users in your organization, including their current\nstatus, the companies involved, and merge details. You can filter company merges using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties:\n\n\n| Property | Type | Operators | Values | Examples |\n|----------|------|-----------|--------|----------|\n| `status` | `enum` | `=` | `in-progress`, `success`, `failed` | `status=failed` |\n| `taskId` | `string` | `=` | | `taskId=789e0123-e45b-67c8-d901-234567890123` |\n\n\nCompany merges are returned in reverse chronological order (most recent first).\n\n\nRequires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and\norganization admin role.\n", + "summary": "Get All Company Merges", + "operationId": "v2_company-merges__GET", "tags": [ - "lists" + "companyMerges" ], "parameters": [ - { - "name": "listId", - "description": "List ID", - "in": "path", - "required": true, - "schema": { - "type": "integer", - "format": "int64", - "minimum": 1, - "maximum": 9223372036854776000 - } - }, { "name": "cursor", "description": "Cursor for the next or previous page", "in": "query", "schema": { "type": "string" - } + }, + "example": "ICAgICAgYmVmb3JlOjo6Nw" }, { "name": "limit", @@ -789,60 +959,99 @@ "minimum": 1, "maximum": 100, "default": 100 - } + }, + "example": 100 }, { - "name": "fieldIds", - "description": "Field IDs for which to return field data", + "name": "filter", + "description": "Filter company merges using Affinity Filtering Language", "in": "query", - "style": "form", - "explode": true, "schema": { - "type": "array", - "items": { - "type": "string", - "format": "string" + "type": "string" + }, + "example": "status=failed | taskId=789e0123-e45b-67c8-d901-234567890123" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CompanyMergeStatePaged" + }, + "examples": { + "merges-list": { + "$ref": "#/components/examples/merges-list" + } + } + } + }, + "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" } } }, - { - "name": "fieldTypes", - "description": "Field Types for which to return field data", - "in": "query", - "style": "form", - "explode": true, - "schema": { - "type": "array", - "items": { - "type": "string", - "format": "string", - "enum": [ - "enriched", - "global", - "list", - "relationship-intelligence" - ] + "400": { + "$ref": "#/components/responses/400" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "default": { + "$ref": "#/components/responses/default" + } + } + }, + "post": { + "description": "Initiate a company merge to combine a duplicate company profile into a primary company profile.\n\nThis is an asynchronous process that will merge all data from the duplicate company into the primary company. Once the merge is initiated, you can track its progress using the returned [task URL](#tag/companyMerges/operation/v2_tasks_company-merges_taskId__GET).\n\nRequires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role.", + "summary": "Initiate Company Merge", + "operationId": "v2_company-merges__POST", + "tags": [ + "companyMerges" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CompanyMergeRequest" + }, + "examples": { + "merge-companies": { + "$ref": "#/components/examples/merge-companies" + } } } } - ], + }, "responses": { - "200": { - "description": "Get all List Entries on a List", + "202": { + "description": "Accepted", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ListEntryWithEntityPaged" + "$ref": "#/components/schemas/CompanyMergeResponse" }, "examples": { - "company-list-enriched": { - "$ref": "#/components/examples/company-list-enriched" - }, - "company-list-relationship-intelligence": { - "$ref": "#/components/examples/company-list-relationship-intelligence" - }, - "company-list-global-and-list": { - "$ref": "#/components/examples/company-list-global-and-list" + "merge-initiated": { + "$ref": "#/components/examples/merge-initiated" } } } @@ -874,101 +1083,54 @@ "403": { "$ref": "#/components/responses/403" }, - "404": { - "$ref": "#/components/responses/404" - }, "default": { "$ref": "#/components/responses/default" } } } }, - "/v2/lists/{listId}/list-entries/{listEntryId}": { + "/v2/company-merges/{mergeId}": { "get": { - "x-stability-level": "beta", - "description": "| ⚠️ This endpoint is currently in BETA |\n|--|\n\nRetrieve a single list entry.\nReturns basic information and field data, including list-specific field data.\n\nTo retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter\nto specify the Fields for which you want data returned.\nThese Field IDs and Types can be found using the GET `/v2/lists/{listId}/fields` endpoint.\nWhen no `fieldIds` or `fieldTypes` are provided, the List Entry will be returned without any field data attached.\nTo supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this:\n`?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`.\n\nRequires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions).", - "summary": "Get a single List Entry on a List [BETA]", - "operationId": "v2_lists_listId_list-entries_listEntryId__GET", + "description": "Retrieve the status and details of a specific company merge.\n\nReturns information about the company merge including its current status, the companies involved, timestamps, and any error information if the merge failed.\n\nThe `mergeId` can be obtained from the response of the [Get All Company Merges](#tag/companyMerges/operation/v2_company-merges__GET) endpoint, or by filtering company merges by task ID using `/v2/company-merges?filter=taskId={taskId}` after initiating a merge.\n\nRequires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role.", + "summary": "Get Company Merge", + "operationId": "v2_company-merges_mergeId__GET", "tags": [ - "lists" + "companyMerges" ], "parameters": [ { - "name": "listId", - "description": "List ID", + "name": "mergeId", + "description": "Company merge ID", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "minimum": 1, - "maximum": 9223372036854776000 - } - }, - { - "name": "listEntryId", - "description": "List Entry ID", - "in": "path", - "required": true, - "schema": { - "type": "integer", - "format": "int64", - "minimum": 1, - "maximum": 9223372036854776000 - } - }, - { - "name": "fieldIds", - "description": "Field IDs for which to return field data", - "in": "query", - "style": "form", - "explode": true, - "schema": { - "type": "array", - "items": { - "type": "string", - "format": "string" - } - } - }, - { - "name": "fieldTypes", - "description": "Field Types for which to return field data", - "in": "query", - "style": "form", - "explode": true, - "schema": { - "type": "array", - "items": { - "type": "string", - "format": "string", - "enum": [ - "enriched", - "global", - "list", - "relationship-intelligence" - ] - } + "maximum": 9007199254740991, + "examples": [ + 12345 + ] } } ], "responses": { "200": { - "description": "The list entry", + "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ListEntryWithEntity" + "$ref": "#/components/schemas/CompanyMergeState" }, "examples": { - "company-list-enriched": { - "$ref": "#/components/examples/company-list-enriched-2" + "completed-merge": { + "$ref": "#/components/examples/succeeded-merge" }, - "company-list-relationship-intelligence": { - "$ref": "#/components/examples/company-list-relationship-intelligence-2" + "failed-merge": { + "$ref": "#/components/examples/failed-merge" }, - "company-list-global-and-list": { - "$ref": "#/components/examples/company-list-global-and-list-2" + "in-progress-merge": { + "$ref": "#/components/examples/in-progress-merge" } } } @@ -1009,81 +1171,113 @@ } } }, - "/v2/lists/{listId}/list-entries/{listEntryId}/fields": { + "/v2/emails": { "get": { - "x-stability-level": "beta", - "description": "\n| ⚠️ This endpoint is currently in BETA |\n|--|\n\nPaginate through all field values on a single list entry.\n\nAll fields will be included by default. The `ids` and `types` parameters can be used to filter the collection.\n\nRequires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions).", - "summary": "Get field values on a single List Entry [BETA]", - "operationId": "v2_lists_listId_list-entries_listEntryId_fields__GET", + "description": "Paginate through all emails in Affinity. Returns basic information about the email interaction\nand its participants. Will only return emails or subject lines that the current authenticated\nuser has permission to see.\n\nYou can filter emails using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties.\n| **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** |\n|-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|----------------------------------|\n| `id` | Unique identifier for Emails | `int64` | `=` | `id=1` |\n| `sentAt` | When the Email was sent at | `datetime` | `>`, `<`, `>=`, `<=` | `sentAt>2025-01-01T01:00:00Z` |\n| `createdAt` | When the Email was created in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-01-01T01:00:00Z` |\n| `updatedAt` | When the Email was updated in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-01-01T01:00:00Z`|\n", + "summary": "Get metadata on all Emails", + "operationId": "v2_emails__GET", "tags": [ - "lists" + "emails" ], "parameters": [ { - "name": "listId", - "description": "List ID", - "in": "path", - "required": true, + "name": "cursor", + "description": "Cursor for the next or previous page", + "in": "query", "schema": { - "type": "integer", - "format": "int64", - "minimum": 1, - "maximum": 9223372036854776000 - } + "type": "string", + "examples": [ + "ICAgICAgYmVmb3JlOjo6Nw" + ] + }, + "example": "ICAgICAgYmVmb3JlOjo6Nw" }, { - "name": "listEntryId", - "description": "List Entry ID", - "in": "path", - "required": true, + "name": "limit", + "description": "Number of items to include in the page", + "in": "query", "schema": { "type": "integer", - "format": "int64", + "format": "int32", "minimum": 1, - "maximum": 9223372036854776000 - } + "maximum": 100, + "default": 100, + "examples": [ + 100 + ] + }, + "example": 100 }, { - "name": "ids", - "description": "Field IDs for which to return field data", + "name": "filter", + "description": "Filter options", "in": "query", - "style": "form", - "explode": true, "schema": { - "type": "array", - "items": { - "type": "string", - "format": "string" + "type": "string" + }, + "example": "id=1234" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/interactions.EmailPaged" + } } - } - }, - { - "name": "types", - "description": "Field Types for which to return field data", - "in": "query", - "style": "form", - "explode": true, - "schema": { - "type": "array", - "items": { - "type": "string", - "format": "string", - "enum": [ - "enriched", - "global", - "list", - "relationship-intelligence" - ] + }, + "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" + }, + "default": { + "$ref": "#/components/responses/default" + } + } + } + }, + "/v2/lists": { + "get": { + "description": "Paginate through all Lists in your organization that you have access to view.\nReturns basic information about each List, including name, owner, and privacy settings.", + "summary": "Get metadata on all Lists", + "operationId": "v2_lists__GET", + "tags": [ + "lists" + ], + "parameters": [ { "name": "cursor", "description": "Cursor for the next or previous page", "in": "query", "schema": { - "type": "string" - } + "type": "string", + "examples": [ + "ICAgICAgYmVmb3JlOjo6Nw" + ] + }, + "example": "ICAgICAgYmVmb3JlOjo6Nw" }, { "name": "limit", @@ -1094,27 +1288,25 @@ "format": "int32", "minimum": 1, "maximum": 100, - "default": 20 - } + "default": 100, + "examples": [ + 100 + ] + }, + "example": 100 } ], "responses": { "200": { - "description": "Paginated fields", + "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/FieldPaged" + "$ref": "#/components/schemas/ListWithTypePaged" }, "examples": { - "company-list-enriched": { - "$ref": "#/components/examples/company-list-enriched-3" - }, - "company-list-relationship-intelligence": { - "$ref": "#/components/examples/company-list-relationship-intelligence-3" - }, - "company-list-global-and-list": { - "$ref": "#/components/examples/company-list-global-and-list-3" + "success": { + "$ref": "#/components/examples/success" } } } @@ -1143,22 +1335,17 @@ "400": { "$ref": "#/components/responses/400" }, - "403": { - "$ref": "#/components/responses/403" - }, - "404": { - "$ref": "#/components/responses/404" - }, "default": { "$ref": "#/components/responses/default" } } - }, - "patch": { - "x-stability-level": "beta", - "description": "| ⚠️ This endpoint is currently in BETA |\n|--|\n\nPerform batch operations on a list entry's fields.\n\nCurrently the only operation at the endpoint is `update-fields`, which allows you to update multiple field values with a single request. This is equivalent to calling [the single field update](#operation/v2_lists_listId_list-entries_listEntryId_fields_fieldId__POST) endpoint multiple times. \n\nRequires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions).", - "summary": "Perform batch operations on a list entry's fields [BETA]", - "operationId": "v2_lists_listId_list-entries_listEntryId_fields__PATCH", + } + }, + "/v2/lists/{listId}": { + "get": { + "description": "Retrieve detailed information about a specific List you have access to view.\nReturns List configuration including name, owner, privacy settings, and creation details.", + "summary": "Get metadata on a single List", + "operationId": "v2_lists_listId__GET", "tags": [ "lists" ], @@ -1174,46 +1361,25 @@ "minimum": 1, "maximum": 9223372036854776000 } - }, - { - "name": "listEntryId", - "description": "List Entry ID", - "in": "path", - "required": true, - "schema": { - "type": "integer", - "format": "int64", - "minimum": 1, - "maximum": 9223372036854776000 - } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ListEntryBatchOperationRequest" - }, - "examples": { - "update-fields": { - "$ref": "#/components/examples/update-fields" - } - } - } - } - }, "responses": { "200": { - "description": "Operation Result", + "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ListEntryBatchOperationResponse" + "$ref": "#/components/schemas/ListWithType" }, "examples": { - "update-fields": { - "$ref": "#/components/examples/update-fields-2" + "company-list": { + "$ref": "#/components/examples/company-list" + }, + "opportunity-list": { + "$ref": "#/components/examples/opportunity-list" + }, + "person-list": { + "$ref": "#/components/examples/person-list" } } } @@ -1242,9 +1408,6 @@ "400": { "$ref": "#/components/responses/400" }, - "403": { - "$ref": "#/components/responses/403" - }, "404": { "$ref": "#/components/responses/404" }, @@ -1254,12 +1417,11 @@ } } }, - "/v2/lists/{listId}/list-entries/{listEntryId}/fields/{fieldId}": { + "/v2/lists/{listId}/fields": { "get": { - "x-stability-level": "beta", - "description": "\n| ⚠️ This endpoint is currently in BETA |\n|--|\n\nReturns a single field value on a list entry.\n\nRequires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions).", - "summary": "Get a single field value [BETA]", - "operationId": "v2_lists_listId_list-entries_listEntryId_fields_fieldId__GET", + "description": "Returns metadata on the Fields available on a single List.\n\nUse the returned Field IDs to request field data from the GET `/v2/lists/{listId}/list-entries` endpoint.", + "summary": "Get metadata on a single List's Fields", + "operationId": "v2_lists_listId_fields__GET", "tags": [ "lists" ], @@ -1277,87 +1439,51 @@ } }, { - "name": "listEntryId", - "description": "List Entry ID", - "in": "path", - "required": true, - "schema": { - "type": "integer", - "format": "int64", - "minimum": 1, - "maximum": 9223372036854776000 - } - }, - { - "name": "fieldId", - "description": "Field ID", - "in": "path", - "required": true, + "name": "cursor", + "description": "Cursor for the next or previous page", + "in": "query", "schema": { "type": "string", - "format": "string" - } + "examples": [ + "ICAgICAgYmVmb3JlOjo6Nw" + ] + }, + "example": "ICAgICAgYmVmb3JlOjo6Nw" + }, + { + "name": "limit", + "description": "Number of items to include in the page", + "in": "query", + "schema": { + "type": "integer", + "format": "int32", + "minimum": 1, + "maximum": 100, + "default": 100, + "examples": [ + 100 + ] + }, + "example": 100 } ], "responses": { "200": { - "description": "The field value", + "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Field" + "$ref": "#/components/schemas/FieldMetadataPaged" }, "examples": { - "company": { - "$ref": "#/components/examples/company" - }, - "company-multi": { - "$ref": "#/components/examples/company-multi" - }, - "datetime": { - "$ref": "#/components/examples/datetime" - }, - "dropdown": { - "$ref": "#/components/examples/dropdown" - }, - "dropdown-multi": { - "$ref": "#/components/examples/dropdown-multi" - }, - "filterable-text": { - "$ref": "#/components/examples/filterable-text" - }, - "filterable-text-multi": { - "$ref": "#/components/examples/filterable-text-multi" - }, - "formula-number": { - "$ref": "#/components/examples/formula-number" - }, - "interaction": { - "$ref": "#/components/examples/interaction" - }, - "location": { - "$ref": "#/components/examples/location" - }, - "location-multi": { - "$ref": "#/components/examples/location-multi" - }, - "number": { - "$ref": "#/components/examples/number" - }, - "number-multi": { - "$ref": "#/components/examples/number-multi" - }, - "person": { - "$ref": "#/components/examples/person" - }, - "person-multi": { - "$ref": "#/components/examples/person-multi" + "company-list": { + "$ref": "#/components/examples/company-list-2" }, - "ranked-dropdown": { - "$ref": "#/components/examples/ranked-dropdown" + "person-list": { + "$ref": "#/components/examples/person-list-2" }, - "text": { - "$ref": "#/components/examples/text" + "opportunity-list": { + "$ref": "#/components/examples/opportunity-list-2" } } } @@ -1386,9 +1512,6 @@ "400": { "$ref": "#/components/responses/400" }, - "403": { - "$ref": "#/components/responses/403" - }, "404": { "$ref": "#/components/responses/404" }, @@ -1396,12 +1519,13 @@ "$ref": "#/components/responses/default" } } - }, - "post": { - "x-stability-level": "beta", - "description": "\n| ⚠️ This endpoint is currently in BETA |\n|--|\n\nUpdate a single field value.\n \nRequires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions).", - "summary": "Update a single field value on a List Entry [BETA]", - "operationId": "v2_lists_listId_list-entries_listEntryId_fields_fieldId__POST", + } + }, + "/v2/lists/{listId}/list-entries": { + "get": { + "description": "Paginate through the List Entries (AKA rows) on a given List.\nReturns basic information and field data, including list-specific\nfield data, on each Company, Person, or Opportunity on the List.\nList Entries also include metadata about their creation,\ni.e., when they were added to the List and by whom.\n\nTo retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter\nto specify the Fields for which you want data returned.\nThese Field IDs and Types can be found using the GET `/v2/lists/{listId}/fields` endpoint.\nWhen no `fieldIds` or `fieldTypes` are provided, List Entries will be returned without any field data attached.\nTo supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this:\n`?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`.\n\nRequires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions).", + "summary": "Get all List Entries on a List", + "operationId": "v2_lists_listId_list-entries__GET", "tags": [ "lists" ], @@ -1419,88 +1543,100 @@ } }, { - "name": "listEntryId", - "description": "List Entry ID", - "in": "path", - "required": true, + "name": "cursor", + "description": "Cursor for the next or previous page", + "in": "query", + "schema": { + "type": "string", + "examples": [ + "ICAgICAgYmVmb3JlOjo6Nw" + ] + }, + "example": "ICAgICAgYmVmb3JlOjo6Nw" + }, + { + "name": "limit", + "description": "Number of items to include in the page", + "in": "query", "schema": { "type": "integer", - "format": "int64", + "format": "int32", "minimum": 1, - "maximum": 9223372036854776000 - } + "maximum": 100, + "default": 100, + "examples": [ + 100 + ] + }, + "example": 100 }, { - "name": "fieldId", - "description": "Field ID", - "in": "path", - "required": true, + "name": "fieldIds", + "description": "Field IDs for which to return field data", + "in": "query", + "style": "form", + "explode": true, "schema": { - "type": "string", - "format": "string" - } + "type": "array", + "items": { + "type": "string" + }, + "examples": [ + [ + "field-1" + ] + ] + }, + "example": [ + "field-1", + "field-2" + ] + }, + { + "name": "fieldTypes", + "description": "Field Types for which to return field data", + "in": "query", + "style": "form", + "explode": true, + "schema": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "enriched", + "global", + "list", + "relationship-intelligence" + ] + } + }, + "example": [ + "enriched", + "global" + ] } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/FieldUpdate" - }, - "examples": { - "company": { - "$ref": "#/components/examples/company-2" - }, - "company-multi": { - "$ref": "#/components/examples/company-multi-2" - }, - "datetime": { - "$ref": "#/components/examples/datetime-2" - }, - "dropdown": { - "$ref": "#/components/examples/dropdown-2" - }, - "dropdown-multi": { - "$ref": "#/components/examples/dropdown-multi-2" - }, - "filterable-text": { - "$ref": "#/components/examples/filterable-text-2" - }, - "filterable-text-multi": { - "$ref": "#/components/examples/filterable-text-multi-2" - }, - "location": { - "$ref": "#/components/examples/location-2" - }, - "location-multi": { - "$ref": "#/components/examples/location-multi-2" - }, - "number": { - "$ref": "#/components/examples/number-2" - }, - "number-multi": { - "$ref": "#/components/examples/number-multi-2" - }, - "person": { - "$ref": "#/components/examples/person-2" - }, - "person-multi": { - "$ref": "#/components/examples/person-multi-2" - }, - "ranked-dropdown": { - "$ref": "#/components/examples/ranked-dropdown-2" + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListEntryWithEntityPaged" }, - "text": { - "$ref": "#/components/examples/text-2" + "examples": { + "company-list-enriched": { + "$ref": "#/components/examples/company-list-enriched" + }, + "company-list-relationship-intelligence": { + "$ref": "#/components/examples/company-list-relationship-intelligence" + }, + "company-list-global-and-list": { + "$ref": "#/components/examples/company-list-global-and-list" + } } } - } - } - }, - "responses": { - "204": { - "description": "No Content", + }, "headers": { "X-Ratelimit-Limit-User": { "$ref": "#/components/headers/X-Ratelimit-Limit-User" @@ -1537,11 +1673,11 @@ } } }, - "/v2/lists/{listId}/fields": { + "/v2/lists/{listId}/list-entries/{listEntryId}": { "get": { - "description": "Returns metadata on the Fields available on a single List.\n\nUse the returned Field IDs to request field data from the GET `/v2/lists/{listId}/list-entries` endpoint.", - "summary": "Get metadata on a single List's Fields", - "operationId": "v2_lists_listId_fields__GET", + "description": "Retrieve a single list entry.\nReturns basic information and field data, including list-specific field data.\n\nTo retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter\nto specify the Fields for which you want data returned.\nThese Field IDs and Types can be found using the GET `/v2/lists/{listId}/fields` endpoint.\nWhen no `fieldIds` or `fieldTypes` are provided, the List Entry will be returned without any field data attached.\nTo supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this:\n`?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`.\n\nRequires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions).", + "summary": "Get a single List Entry on a List", + "operationId": "v2_lists_listId_list-entries_listEntryId__GET", "tags": [ "lists" ], @@ -1559,43 +1695,80 @@ } }, { - "name": "cursor", - "description": "Cursor for the next or previous page", - "in": "query", + "name": "listEntryId", + "description": "List Entry ID", + "in": "path", + "required": true, "schema": { - "type": "string" + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9223372036854776000 } }, { - "name": "limit", - "description": "Number of items to include in the page", + "name": "fieldIds", + "description": "Field IDs for which to return field data", "in": "query", + "style": "form", + "explode": true, "schema": { - "type": "integer", - "format": "int32", - "minimum": 1, - "maximum": 100, - "default": 100 - } + "type": "array", + "items": { + "type": "string" + }, + "examples": [ + [ + "field-1" + ] + ] + }, + "example": [ + "field-1", + "field-2" + ] + }, + { + "name": "fieldTypes", + "description": "Field Types for which to return field data", + "in": "query", + "style": "form", + "explode": true, + "schema": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "enriched", + "global", + "list", + "relationship-intelligence" + ] + } + }, + "example": [ + "enriched", + "global" + ] } ], "responses": { "200": { - "description": "Get metadata on a single List's Fields", + "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/FieldMetadataPaged" + "$ref": "#/components/schemas/ListEntryWithEntity" }, "examples": { - "company-list": { - "$ref": "#/components/examples/company-list-2" + "company-list-enriched": { + "$ref": "#/components/examples/company-list-enriched-2" }, - "person-list": { - "$ref": "#/components/examples/person-list-2" + "company-list-relationship-intelligence": { + "$ref": "#/components/examples/company-list-relationship-intelligence-2" }, - "opportunity-list": { - "$ref": "#/components/examples/opportunity-list-2" + "company-list-global-and-list": { + "$ref": "#/components/examples/company-list-global-and-list-2" } } } @@ -1624,6 +1797,9 @@ "400": { "$ref": "#/components/responses/400" }, + "403": { + "$ref": "#/components/responses/403" + }, "404": { "$ref": "#/components/responses/404" }, @@ -1633,11 +1809,11 @@ } } }, - "/v2/lists/{listId}/saved-views": { + "/v2/lists/{listId}/list-entries/{listEntryId}/fields": { "get": { - "description": "Returns metadata on the Saved Views on a List.", - "summary": "Get metadata on Saved Views", - "operationId": "getV2ListsListidSavedViews", + "description": "Paginate through all field values on a single list entry.\n\nAll fields will be included by default. The `ids` and `types` parameters can be used to filter the collection.\n\nRequires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions).", + "summary": "Get field values on a single List Entry", + "operationId": "v2_lists_listId_list-entries_listEntryId_fields__GET", "tags": [ "lists" ], @@ -1654,13 +1830,74 @@ "maximum": 9223372036854776000 } }, + { + "name": "listEntryId", + "description": "List Entry ID", + "in": "path", + "required": true, + "schema": { + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9223372036854776000 + } + }, + { + "name": "ids", + "description": "Field IDs for which to return field data", + "in": "query", + "style": "form", + "explode": true, + "schema": { + "type": "array", + "items": { + "type": "string" + }, + "examples": [ + [ + "field-1" + ] + ] + }, + "example": [ + "field-1", + "field-2" + ] + }, + { + "name": "types", + "description": "Field Types for which to return field data", + "in": "query", + "style": "form", + "explode": true, + "schema": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "enriched", + "global", + "list", + "relationship-intelligence" + ] + } + }, + "example": [ + "enriched", + "global" + ] + }, { "name": "cursor", "description": "Cursor for the next or previous page", "in": "query", "schema": { - "type": "string" - } + "type": "string", + "examples": [ + "ICAgICAgYmVmb3JlOjo6Nw" + ] + }, + "example": "ICAgICAgYmVmb3JlOjo6Nw" }, { "name": "limit", @@ -1671,17 +1908,32 @@ "format": "int32", "minimum": 1, "maximum": 100, - "default": 100 - } + "default": 20, + "examples": [ + 20 + ] + }, + "example": 20 } ], "responses": { "200": { - "description": "Get metadata on Saved Views", + "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SavedViewPaged" + "$ref": "#/components/schemas/FieldPaged" + }, + "examples": { + "company-list-enriched": { + "$ref": "#/components/examples/company-list-enriched-3" + }, + "company-list-relationship-intelligence": { + "$ref": "#/components/examples/company-list-relationship-intelligence-3" + }, + "company-list-global-and-list": { + "$ref": "#/components/examples/company-list-global-and-list-3" + } } } }, @@ -1709,6 +1961,9 @@ "400": { "$ref": "#/components/responses/400" }, + "403": { + "$ref": "#/components/responses/403" + }, "404": { "$ref": "#/components/responses/404" }, @@ -1716,13 +1971,11 @@ "$ref": "#/components/responses/default" } } - } - }, - "/v2/lists/{listId}/saved-views/{viewId}": { - "get": { - "description": "Returns metadata on a single Saved View.", - "summary": "Get metadata on a single Saved View", - "operationId": "getV2ListsListidSavedViewsViewid", + }, + "patch": { + "description": "Perform batch operations on a list entry's fields.\n\nCurrently the only operation at the endpoint is `update-fields`, which allows you to update multiple field values with a single request. This is equivalent to calling [the single field update](#operation/v2_lists_listId_list-entries_listEntryId_fields_fieldId__POST) endpoint multiple times. \n\nRequires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions).", + "summary": "Perform batch operations on a list entry's fields", + "operationId": "v2_lists_listId_list-entries_listEntryId_fields__PATCH", "tags": [ "lists" ], @@ -1740,8 +1993,8 @@ } }, { - "name": "viewId", - "description": "Saved view ID", + "name": "listEntryId", + "description": "List Entry ID", "in": "path", "required": true, "schema": { @@ -1752,13 +2005,33 @@ } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListEntryBatchOperationRequest" + }, + "examples": { + "update-fields": { + "$ref": "#/components/examples/update-fields" + } + } + } + } + }, "responses": { "200": { - "description": "Get metadata on a single Saved View", + "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SavedView" + "$ref": "#/components/schemas/ListEntryBatchOperationResponse" + }, + "examples": { + "update-fields": { + "$ref": "#/components/examples/update-fields-2" + } } } }, @@ -1786,6 +2059,9 @@ "400": { "$ref": "#/components/responses/400" }, + "403": { + "$ref": "#/components/responses/403" + }, "404": { "$ref": "#/components/responses/404" }, @@ -1795,11 +2071,11 @@ } } }, - "/v2/lists/{listId}/saved-views/{viewId}/list-entries": { + "/v2/lists/{listId}/list-entries/{listEntryId}/fields/{fieldId}": { "get": { - "description": "Paginate through the List Entries (AKA rows) on a given Saved View.\nUse this endpoint when you need to filter entities or only want **some**\nfield data to be returned: This endpoint respects the filters set on a Saved View\nvia web app, and only returns field data corresponding to the columns that have been\npulled into the Saved View via web app.\n\nThough this endpoint respects the Saved View's filters and column/Field selection,\nit does not yet preserve sort order. This endpoint also only supports **sheet-type\nSaved Views**, and not board- or dashboard-type Saved Views.\n\nSee the [Data Model](#section/Data-Model) section for more information about Saved Views.\n\nRequires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions).", - "summary": "Get all List Entries on a Saved View", - "operationId": "getV2ListsListidSavedViewsViewidListEntries", + "description": "Returns a single field value on a list entry.\n\nRequires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions).", + "summary": "Get a single field value", + "operationId": "v2_lists_listId_list-entries_listEntryId_fields_fieldId__GET", "tags": [ "lists" ], @@ -1817,8 +2093,8 @@ } }, { - "name": "viewId", - "description": "Saved view ID", + "name": "listEntryId", + "description": "List Entry ID", "in": "path", "required": true, "schema": { @@ -1829,128 +2105,220 @@ } }, { - "name": "cursor", - "description": "Cursor for the next or previous page", - "in": "query", - "schema": { - "type": "string" - } - }, - { - "name": "limit", - "description": "Number of items to include in the page", - "in": "query", + "name": "fieldId", + "description": "Field ID", + "in": "path", + "required": true, "schema": { - "type": "integer", - "format": "int32", - "minimum": 1, - "maximum": 100, - "default": 100 - } + "type": "string", + "examples": [ + "affinity-data-location", + "field-1234" + ] + }, + "example": "field-1234" } ], "responses": { "200": { - "description": "Get all List Entries on a Saved View", + "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ListEntryWithEntityPaged" - } - } - }, - "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" - } - } - } - }, - "/v2/opportunities": { - "get": { - "description": "Paginate through Opportunities in Affinity.\nReturns basic information but **not** field data on each Opportunity.\n\nTo access field data on Opportunities, use the `/lists/{list_id}/list-entries`\nor the `/v2/lists/{list_id}/saved-views/{view_id}/list-entries` GET endpoint.\n\nRequires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions).", - "summary": "Get all Opportunities", - "operationId": "getV2Opportunities", + "$ref": "#/components/schemas/Field" + }, + "examples": { + "company": { + "$ref": "#/components/examples/company" + }, + "company-multi": { + "$ref": "#/components/examples/company-multi" + }, + "datetime": { + "$ref": "#/components/examples/datetime" + }, + "dropdown": { + "$ref": "#/components/examples/dropdown" + }, + "dropdown-multi": { + "$ref": "#/components/examples/dropdown-multi" + }, + "filterable-text": { + "$ref": "#/components/examples/filterable-text" + }, + "filterable-text-multi": { + "$ref": "#/components/examples/filterable-text-multi" + }, + "formula-number": { + "$ref": "#/components/examples/formula-number" + }, + "interaction": { + "$ref": "#/components/examples/interaction" + }, + "location": { + "$ref": "#/components/examples/location" + }, + "location-multi": { + "$ref": "#/components/examples/location-multi" + }, + "number": { + "$ref": "#/components/examples/number" + }, + "number-multi": { + "$ref": "#/components/examples/number-multi" + }, + "person": { + "$ref": "#/components/examples/person" + }, + "person-multi": { + "$ref": "#/components/examples/person-multi" + }, + "ranked-dropdown": { + "$ref": "#/components/examples/ranked-dropdown" + }, + "text": { + "$ref": "#/components/examples/text" + } + } + } + }, + "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" + } + } + }, + "post": { + "description": "Update a single field value.\n \nRequires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions).", + "summary": "Update a single field value on a List Entry", + "operationId": "v2_lists_listId_list-entries_listEntryId_fields_fieldId__POST", "tags": [ - "opportunities" + "lists" ], "parameters": [ { - "name": "cursor", - "description": "Cursor for the next or previous page", - "in": "query", + "name": "listId", + "description": "List ID", + "in": "path", + "required": true, "schema": { - "type": "string" + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9223372036854776000 } }, { - "name": "limit", - "description": "Number of items to include in the page", - "in": "query", + "name": "listEntryId", + "description": "List Entry ID", + "in": "path", + "required": true, "schema": { "type": "integer", - "format": "int32", + "format": "int64", "minimum": 1, - "maximum": 100, - "default": 100 + "maximum": 9223372036854776000 } }, { - "name": "ids", - "description": "Opportunity IDs", - "in": "query", - "style": "form", - "explode": true, + "name": "fieldId", + "description": "Field ID", + "in": "path", + "required": true, "schema": { - "type": "array", - "items": { - "type": "integer", - "format": "int64", - "minimum": 1, - "maximum": 9223372036854776000 - } + "type": "string" } } ], - "responses": { - "200": { - "description": "Get all Opportunities", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/OpportunityPaged" + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FieldUpdate" + }, + "examples": { + "company": { + "$ref": "#/components/examples/company-2" + }, + "company-multi": { + "$ref": "#/components/examples/company-multi-2" + }, + "datetime": { + "$ref": "#/components/examples/datetime-2" + }, + "dropdown": { + "$ref": "#/components/examples/dropdown-2" + }, + "dropdown-multi": { + "$ref": "#/components/examples/dropdown-multi-2" + }, + "filterable-text": { + "$ref": "#/components/examples/filterable-text-2" + }, + "filterable-text-multi": { + "$ref": "#/components/examples/filterable-text-multi-2" + }, + "location": { + "$ref": "#/components/examples/location-2" + }, + "location-multi": { + "$ref": "#/components/examples/location-multi-2" + }, + "number": { + "$ref": "#/components/examples/number-2" + }, + "number-multi": { + "$ref": "#/components/examples/number-multi-2" + }, + "person": { + "$ref": "#/components/examples/person-2" + }, + "person-multi": { + "$ref": "#/components/examples/person-multi-2" + }, + "ranked-dropdown": { + "$ref": "#/components/examples/ranked-dropdown-2" + }, + "text": { + "$ref": "#/components/examples/text-2" } } - }, + } + } + }, + "responses": { + "204": { + "description": "No Content", "headers": { "X-Ratelimit-Limit-User": { "$ref": "#/components/headers/X-Ratelimit-Limit-User" @@ -1987,18 +2355,18 @@ } } }, - "/v2/opportunities/{id}": { + "/v2/lists/{listId}/saved-views": { "get": { - "description": "Returns basic information but **not** field data on the requested Opportunity.\n\nTo access field data on Opportunities, use the `/lists/{list_id}/list-entries`\nor the `/v2/lists/{list_id}/saved-views/{view_id}/list-entries` GET endpoint.\n\nRequires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions).", - "summary": "Get a single Opportunity", - "operationId": "getV2OpportunitiesId", + "description": "Paginate through all Saved Views you have access to view for a specific List.\nReturns Saved View configurations including name, column settings, and owner information.", + "summary": "Get metadata on Saved Views", + "operationId": "v2_lists_listId_saved-views__GET", "tags": [ - "opportunities" + "lists" ], "parameters": [ { - "name": "id", - "description": "Opportunity ID", + "name": "listId", + "description": "List ID", "in": "path", "required": true, "schema": { @@ -2007,15 +2375,43 @@ "minimum": 1, "maximum": 9223372036854776000 } + }, + { + "name": "cursor", + "description": "Cursor for the next or previous page", + "in": "query", + "schema": { + "type": "string", + "examples": [ + "ICAgICAgYmVmb3JlOjo6Nw" + ] + }, + "example": "ICAgICAgYmVmb3JlOjo6Nw" + }, + { + "name": "limit", + "description": "Number of items to include in the page", + "in": "query", + "schema": { + "type": "integer", + "format": "int32", + "minimum": 1, + "maximum": 100, + "default": 100, + "examples": [ + 100 + ] + }, + "example": 100 } ], "responses": { "200": { - "description": "Get a single Opportunity", + "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Opportunity" + "$ref": "#/components/schemas/SavedViewPaged" } } }, @@ -2043,9 +2439,6 @@ "400": { "$ref": "#/components/responses/400" }, - "403": { - "$ref": "#/components/responses/403" - }, "404": { "$ref": "#/components/responses/404" }, @@ -2055,92 +2448,47 @@ } } }, - "/v2/persons": { + "/v2/lists/{listId}/saved-views/{viewId}": { "get": { - "description": "Paginate through Persons in Affinity.\nReturns basic information and non-list-specific field data on each Person.\n\nTo retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter\nto specify the Fields for which you want data returned.\nThese Field IDs and Types can be found using the GET `/v2/persons/fields` endpoint.\nWhen no `fieldIds` or `fieldTypes` are provided, Persons will be returned without any field data attached.\nTo supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this:\n`?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`.\n\nRequires the \"Export All People directory\" [permission](#section/Getting-Started/Permissions).", - "summary": "Get all Persons", - "operationId": "getV2Persons", + "description": "Retrieve detailed information about a specific Saved View you have access to view.\nReturns complete Saved View configuration including name, sorting, and column visibility settings.", + "summary": "Get metadata on a single Saved View", + "operationId": "v2_lists_listId_saved-views_viewId__GET", "tags": [ - "persons" + "lists" ], "parameters": [ { - "name": "cursor", - "description": "Cursor for the next or previous page", - "in": "query", - "schema": { - "type": "string" - } - }, - { - "name": "limit", - "description": "Number of items to include in the page", - "in": "query", + "name": "listId", + "description": "List ID", + "in": "path", + "required": true, "schema": { "type": "integer", - "format": "int32", + "format": "int64", "minimum": 1, - "maximum": 100, - "default": 100 - } - }, - { - "name": "ids", - "description": "People IDs", - "in": "query", - "style": "form", - "explode": true, - "schema": { - "type": "array", - "items": { - "type": "integer", - "format": "int64", - "minimum": 1, - "maximum": 9223372036854776000 - } - } - }, - { - "name": "fieldIds", - "description": "Field IDs for which to return field data", - "in": "query", - "style": "form", - "explode": true, - "schema": { - "type": "array", - "items": { - "type": "string", - "format": "string" - } + "maximum": 9223372036854776000 } }, { - "name": "fieldTypes", - "description": "Field Types for which to return field data", - "in": "query", - "style": "form", - "explode": true, + "name": "viewId", + "description": "Saved view ID", + "in": "path", + "required": true, "schema": { - "type": "array", - "items": { - "type": "string", - "format": "string", - "enum": [ - "enriched", - "global", - "relationship-intelligence" - ] - } + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9223372036854776000 } } ], "responses": { "200": { - "description": "Get all Persons", + "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PersonPaged" + "$ref": "#/components/schemas/SavedView" } } }, @@ -2168,8 +2516,8 @@ "400": { "$ref": "#/components/responses/400" }, - "403": { - "$ref": "#/components/responses/403" + "404": { + "$ref": "#/components/responses/404" }, "default": { "$ref": "#/components/responses/default" @@ -2177,18 +2525,18 @@ } } }, - "/v2/persons/{id}": { + "/v2/lists/{listId}/saved-views/{viewId}/list-entries": { "get": { - "description": "Returns basic information and non-list-specific field data on the requested Person.\n\nTo retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter\nto specify the Fields for which you want data returned.\nThese Field IDs and Types can be found using the GET `/v2/persons/fields` endpoint.\nWhen no `fieldIds` or `fieldTypes` are provided, Persons will be returned without any field data attached.\nTo supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this:\n`?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`.\n\nRequires the \"Export All People directory\" [permission](#section/Getting-Started/Permissions).", - "summary": "Get a single Person", - "operationId": "getV2PersonsId", + "description": "Paginate through the List Entries (AKA rows) on a given Saved View.\nUse this endpoint when you need to filter entities or only want **some**\nfield data to be returned: This endpoint respects the filters set on a Saved View\nvia web app, and only returns field data corresponding to the columns that have been\npulled into the Saved View via web app.\n\nThough this endpoint respects the Saved View's filters and column/Field selection,\nit does not yet preserve sort order. This endpoint also only supports **sheet-type\nSaved Views**, and not board- or dashboard-type Saved Views.\n\nSee the [Data Model](#section/Data-Model) section for more information about Saved Views.\n\nRequires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions).", + "summary": "Get all List Entries on a Saved View", + "operationId": "v2_lists_listId_saved-views_viewId_list-entries__GET", "tags": [ - "persons" + "lists" ], "parameters": [ { - "name": "id", - "description": "Person ID", + "name": "listId", + "description": "List ID", "in": "path", "required": true, "schema": { @@ -2199,46 +2547,53 @@ } }, { - "name": "fieldIds", - "description": "Field IDs for which to return field data", - "in": "query", - "style": "form", - "explode": true, + "name": "viewId", + "description": "Saved view ID", + "in": "path", + "required": true, "schema": { - "type": "array", - "items": { - "type": "string", - "format": "string" - } + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9223372036854776000 } }, { - "name": "fieldTypes", - "description": "Field Types for which to return field data", + "name": "cursor", + "description": "Cursor for the next or previous page", "in": "query", - "style": "form", - "explode": true, "schema": { - "type": "array", - "items": { - "type": "string", - "format": "string", - "enum": [ - "enriched", - "global", - "relationship-intelligence" - ] - } - } + "type": "string", + "examples": [ + "ICAgICAgYmVmb3JlOjo6Nw" + ] + }, + "example": "ICAgICAgYmVmb3JlOjo6Nw" + }, + { + "name": "limit", + "description": "Number of items to include in the page", + "in": "query", + "schema": { + "type": "integer", + "format": "int32", + "minimum": 1, + "maximum": 100, + "default": 100, + "examples": [ + 100 + ] + }, + "example": 100 } ], "responses": { "200": { - "description": "Get a single Person", + "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Person" + "$ref": "#/components/schemas/ListEntryWithEntityPaged" } } }, @@ -2278,13 +2633,13 @@ } } }, - "/v2/persons/fields": { + "/v2/meetings": { "get": { - "description": "Returns metadata on non-list-specific Person Fields.\n\nUse the returned Field IDs to request field data from the GET `/v2/persons` and GET `/v2/persons/{id}` endpoints.", - "summary": "Get metadata on Person Fields", - "operationId": "getV2PersonsFields", + "description": "Paginate through all Meetings in Affinity. Returns basic information about past and future meeting interactions\nand its attendees.\n\nYou can filter meetings using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties.\n| **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** |\n|-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|----------------------------------|\n| `id` | Unique identifier for Meetings | `int64` | `=` | `id=1` |\n| `startTime` | Start time of when Meeting was scheduled | `datetime` | `>`, `<`, `>=`, `<=` | `startTime>2025-01-01T01:00:00Z` |\n| `createdAt` | When the Meeting was created in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-01-01T01:00:00Z` |\n| `updatedAt` | When the Meeting was updated in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-01-01T01:00:00Z`|\n", + "summary": "Get metadata on all Meetings", + "operationId": "v2_meetings__GET", "tags": [ - "persons" + "meetings" ], "parameters": [ { @@ -2292,8 +2647,12 @@ "description": "Cursor for the next or previous page", "in": "query", "schema": { - "type": "string" - } + "type": "string", + "examples": [ + "ICAgICAgYmVmb3JlOjo6Nw" + ] + }, + "example": "ICAgICAgYmVmb3JlOjo6Nw" }, { "name": "limit", @@ -2304,17 +2663,30 @@ "format": "int32", "minimum": 1, "maximum": 100, - "default": 100 - } + "default": 100, + "examples": [ + 100 + ] + }, + "example": 100 + }, + { + "name": "filter", + "description": "Filter options", + "in": "query", + "schema": { + "type": "string" + }, + "example": "id=1234" } ], "responses": { "200": { - "description": "Get metadata on Person Fields", + "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/FieldMetadataPaged" + "$ref": "#/components/schemas/interactions.MeetingPaged" } } }, @@ -2348,31 +2720,30 @@ } } }, - "/v2/persons/{id}/lists": { + "/v2/notes": { "get": { - "description": "Returns metadata for all the Lists on which the given Person appears.", - "summary": "Get a Person's Lists", - "operationId": "getV2PersonsIdLists", + "x-stability-level": "beta", + "description": "| ⚠️ This endpoint is currently in BETA |\n|--|\n\nReturns all notes, with the exception of replies.\nYou can filter notes using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties.\n| **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** |\n|-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|---------------------------------|\n| `id` | Filter notes by id | `int32` | `=` | `id=1` |\n| `creator.id` | Filter notes by the creator of the note | `int32` | `=` | `creator.id=1` |\n| `createdAt` | Filter notes by when it was created | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-02-04T10:48:24Z` |\n| `updatedAt` | Filter notes by when it was updated | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-02-03T10:48:24Z`|\n", + "summary": "Get all Notes", + "operationId": "v2_notes__GET", "tags": [ - "persons" + "notes" ], "parameters": [ { - "name": "id", - "description": "Persons ID", - "in": "path", - "required": true, + "name": "totalCount", + "description": "Include total count of the collection in the pagination response", + "in": "query", "schema": { - "type": "integer", - "format": "int64", - "minimum": 1, - "maximum": 9223372036854776000 + "type": "boolean", + "default": false } }, { "name": "cursor", "description": "Cursor for the next or previous page", "in": "query", + "required": false, "schema": { "type": "string" } @@ -2381,22 +2752,45 @@ "name": "limit", "description": "Number of items to include in the page", "in": "query", + "required": false, "schema": { "type": "integer", "format": "int32", - "minimum": 1, + "minimum": 0, "maximum": 100, - "default": 100 + "default": 20 + } + }, + { + "name": "filter", + "description": "Filter options", + "in": "query", + "schema": { + "type": "string" } + }, + { + "$ref": "#/components/parameters/notes.includes" } ], "responses": { "200": { - "description": "Get a Person's Lists", + "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ListPaged" + "$ref": "#/components/schemas/notes.NotesPaged" + }, + "examples": { + "ai-notetaker": { + "$ref": "#/components/examples/ai-notetaker" + }, + "entities": { + "$ref": "#/components/examples/entities" + }, + "interaction": { + "$ref": "#/components/examples/interaction-2" + } } } }, @@ -2433,55 +2827,56 @@ } } }, - "/v2/persons/{id}/list-entries": { + "/v2/notes/{noteId}": { "get": { - "description": "Paginate through the List Entries (AKA rows) for the given Person across all Lists.\nEach List Entry includes field data for the Person, including list-specific field data.\nEach List Entry also includes metadata about its creation, i.e., when it was added to the List and by whom.\n\nRequires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions).", - "summary": "Get a Person's List Entries", - "operationId": "getV2PersonsIdListEntries", + "x-stability-level": "beta", + "description": "| ⚠️ This endpoint is currently in BETA |\n|--|\n\nGet a Note with a given id\n", + "summary": "Get a single Note", + "operationId": "v2_notes_noteId__GET", "tags": [ - "persons" + "notes" ], "parameters": [ { - "name": "id", - "description": "Persons ID", + "name": "noteId", + "description": "The id of the Note", "in": "path", "required": true, "schema": { "type": "integer", - "format": "int64", + "format": "int32", "minimum": 1, - "maximum": 9223372036854776000 - } - }, - { - "name": "cursor", - "description": "Cursor for the next or previous page", - "in": "query", - "schema": { - "type": "string" + "maximum": 2147483647 } }, { - "name": "limit", - "description": "Number of items to include in the page", - "in": "query", - "schema": { - "type": "integer", - "format": "int32", - "minimum": 1, - "maximum": 100, - "default": 100 - } + "$ref": "#/components/parameters/note.includes" } ], "responses": { "200": { - "description": "Get a Person's List Entries", + "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ListEntryPaged" + "$ref": "#/components/schemas/notes.Note" + }, + "examples": { + "ai-notetaker": { + "$ref": "#/components/examples/ai-notetaker-2" + }, + "ai-notetaker-reply": { + "$ref": "#/components/examples/ai-notetaker-reply" + }, + "entities": { + "$ref": "#/components/examples/entities-2" + }, + "interaction": { + "$ref": "#/components/examples/interaction-3" + }, + "user-reply": { + "$ref": "#/components/examples/user-reply" + } } } }, @@ -2509,9 +2904,6 @@ "400": { "$ref": "#/components/responses/400" }, - "403": { - "$ref": "#/components/responses/403" - }, "404": { "$ref": "#/components/responses/404" }, @@ -2520,2619 +2912,2397 @@ } } } - } - }, - "components": { - "securitySchemes": { - "bearerAuth": { - "type": "http", - "scheme": "bearer" - } }, - "headers": { - "X-Ratelimit-Limit-User": { - "description": "Number of requests allowed per minute for the user", - "schema": { - "type": "integer" - } - }, - "X-Ratelimit-Limit-User-Remaining": { - "description": "Number of requests remaining for the user", - "schema": { - "type": "integer" - } - }, - "X-Ratelimit-Limit-User-Reset": { - "description": "Time in seconds before the limit resets for the user", - "schema": { - "type": "integer" - } - }, - "X-Ratelimit-Limit-Org": { - "description": "Number of requests allowed per month for the account", - "schema": { - "type": "integer" - } - }, - "X-Ratelimit-Limit-Org-Remaining": { - "description": "Number of requests remaining for the account", - "schema": { - "type": "integer" - } - }, - "X-Ratelimit-Limit-Org-Reset": { - "description": "Time in seconds before the limit resets for the account", - "schema": { - "type": "integer" - } - } - }, - "schemas": { - "AuthenticationError": { - "title": "AuthenticationError", - "type": "object", - "properties": { - "code": { - "description": "Error code", - "type": "string", - "const": "authentication" - }, - "message": { - "description": "Error message", - "type": "string" - } - }, - "required": [ - "code", - "message" + "/v2/notes/{noteId}/attached-companies": { + "get": { + "x-stability-level": "beta", + "description": "| ⚠️ This endpoint is currently in BETA |\n|--|\n\nReturns directly attached companies for a given Note.\n", + "summary": "Get Companies attached to a Note", + "operationId": "v2_notes_noteId_attached-companies__GET", + "tags": [ + "notes" ], - "additionalProperties": false, - "examples": [ + "parameters": [ { - "code": "authentication", - "message": "🚨 Error! Sound the alarm! 🚨" - } - ] - }, - "AuthorizationError": { - "title": "AuthorizationError", - "type": "object", - "properties": { - "code": { - "description": "Error code", - "type": "string", - "const": "authorization" + "name": "noteId", + "description": "The id of the Note to get attached Companies", + "in": "path", + "required": true, + "schema": { + "type": "integer", + "format": "int32", + "minimum": 1, + "maximum": 2147483647 + } }, - "message": { - "description": "Error message", - "type": "string" - } - }, - "required": [ - "code", - "message" - ], - "additionalProperties": false, - "examples": [ { - "code": "authorization", - "message": "🚨 Error! Sound the alarm! 🚨" - } - ] - }, - "BadRequestError": { - "title": "BadRequestError", - "type": "object", - "properties": { - "code": { - "description": "Error code", - "type": "string", - "const": "bad-request" + "name": "totalCount", + "description": "Include total count of the collection in the pagination response", + "in": "query", + "schema": { + "type": "boolean", + "default": false + } }, - "message": { - "description": "Error message", - "type": "string" - } - }, - "required": [ - "code", - "message" - ], - "additionalProperties": false, - "examples": [ { - "code": "bad-request", - "message": "🚨 Error! Sound the alarm! 🚨" - } - ] - }, - "ConflictError": { - "title": "ConflictError", - "type": "object", - "properties": { - "code": { - "description": "Error code", - "type": "string", - "const": "conflict" + "name": "cursor", + "description": "Cursor for the next or previous page", + "in": "query", + "required": false, + "schema": { + "type": "string" + } }, - "message": { - "description": "Error message", - "type": "string" - } - }, - "required": [ - "code", - "message" - ], - "additionalProperties": false, - "examples": [ { - "code": "conflict", - "message": "🚨 Error! Sound the alarm! 🚨" + "name": "limit", + "description": "Number of items to include in the page", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "format": "int32", + "minimum": 0, + "maximum": 100, + "default": 20 + } } - ] - }, - "MethodNotAllowedError": { - "title": "MethodNotAllowedError", - "type": "object", - "properties": { - "code": { - "description": "Error code", - "type": "string", - "const": "method-not-allowed" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CompanyDataPaged" + } + } + }, + "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" + } + } }, - "message": { - "description": "Error message", - "type": "string" + "400": { + "$ref": "#/components/responses/400" + }, + "404": { + "$ref": "#/components/responses/404" + }, + "default": { + "$ref": "#/components/responses/default" } - }, - "required": [ - "code", - "message" + } + } + }, + "/v2/notes/{noteId}/attached-opportunities": { + "get": { + "x-stability-level": "beta", + "description": "| ⚠️ This endpoint is currently in BETA |\n|--|\n\nReturns directly attached opportunities for a given Note.\n", + "summary": "Get Opportunities attached to a Note", + "operationId": "v2_notes_noteId_attached-opportunities__GET", + "tags": [ + "notes" ], - "additionalProperties": false, - "examples": [ + "parameters": [ { - "code": "method-not-allowed", - "message": "🚨 Error! Sound the alarm! 🚨" - } - ] - }, - "NotAcceptableError": { - "title": "NotAcceptableError", - "type": "object", - "properties": { - "code": { - "description": "Error code", - "type": "string", - "const": "not-acceptable" + "name": "noteId", + "description": "The id of the Note to get attached Opportunities", + "in": "path", + "required": true, + "schema": { + "type": "integer", + "format": "int32", + "minimum": 1, + "maximum": 2147483647 + } }, - "message": { - "description": "Error message", - "type": "string" - } - }, - "required": [ - "code", - "message" - ], - "additionalProperties": false, - "examples": [ { - "code": "not-acceptable", - "message": "🚨 Error! Sound the alarm! 🚨" - } - ] - }, - "NotFoundError": { - "title": "NotFoundError", - "type": "object", - "properties": { - "code": { - "description": "Error code", - "type": "string", - "const": "not-found" + "name": "totalCount", + "description": "Include total count of the collection in the pagination response", + "in": "query", + "schema": { + "type": "boolean", + "default": false + } }, - "message": { - "description": "Error message", - "type": "string" - } - }, - "required": [ - "code", - "message" - ], - "additionalProperties": false, - "examples": [ - { - "code": "not-found", - "message": "🚨 Error! Sound the alarm! 🚨" - } - ] - }, - "NotImplementedError": { - "title": "NotImplementedError", - "type": "object", - "properties": { - "code": { - "description": "Error code", - "type": "string", - "const": "not-implemented" - }, - "message": { - "description": "Error message", - "type": "string" - } - }, - "required": [ - "code", - "message" - ], - "additionalProperties": false, - "examples": [ { - "code": "not-implemented", - "message": "🚨 Error! Sound the alarm! 🚨" - } - ] - }, - "RateLimitError": { - "title": "RateLimitError", - "type": "object", - "properties": { - "code": { - "description": "Error code", - "type": "string", - "const": "rate-limit" - }, - "message": { - "description": "Error message", - "type": "string" - } - }, - "required": [ - "code", - "message" - ], - "additionalProperties": false, - "examples": [ - { - "code": "rate-limit", - "message": "🚨 Error! Sound the alarm! 🚨" - } - ] - }, - "ServerError": { - "title": "ServerError", - "type": "object", - "properties": { - "code": { - "description": "Error code", - "type": "string", - "const": "server" + "name": "cursor", + "description": "Cursor for the next or previous page", + "in": "query", + "required": false, + "schema": { + "type": "string" + } }, - "message": { - "description": "Error message", - "type": "string" - } - }, - "required": [ - "code", - "message" - ], - "additionalProperties": false, - "examples": [ { - "code": "server", - "message": "🚨 Error! Sound the alarm! 🚨" - } - ] - }, - "UnprocessableEntityError": { - "title": "UnprocessableEntityError", - "type": "object", - "properties": { - "code": { - "description": "Error code", - "type": "string", - "const": "unprocessable-entity" - }, - "message": { - "description": "Error message", - "type": "string" + "name": "limit", + "description": "Number of items to include in the page", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "format": "int32", + "minimum": 0, + "maximum": 100, + "default": 20 + } } - }, - "required": [ - "code", - "message" ], - "additionalProperties": false, - "examples": [ - { - "code": "unprocessable-entity", - "message": "🚨 Error! Sound the alarm! 🚨" - } - ] - }, - "UnsupportedMediaTypeError": { - "title": "UnsupportedMediaTypeError", - "type": "object", - "properties": { - "code": { - "description": "Error code", - "type": "string", - "const": "unsupported-media-type" + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OpportunityPaged" + }, + "examples": { + "success": { + "$ref": "#/components/examples/success-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" + } + } }, - "message": { - "description": "Error message", - "type": "string" - } - }, - "required": [ - "code", - "message" - ], - "additionalProperties": false, - "examples": [ - { - "code": "unsupported-media-type", - "message": "🚨 Error! Sound the alarm! 🚨" - } - ] - }, - "ValidationError": { - "title": "ValidationError", - "type": "object", - "properties": { - "code": { - "description": "Error code", - "type": "string", - "const": "validation" + "400": { + "$ref": "#/components/responses/400" }, - "message": { - "description": "Error message", - "type": "string" + "404": { + "$ref": "#/components/responses/404" }, - "param": { - "description": "Param the error refers to", - "type": "string" + "default": { + "$ref": "#/components/responses/default" } - }, - "required": [ - "code", - "message", - "param" + } + } + }, + "/v2/notes/{noteId}/attached-persons": { + "get": { + "x-stability-level": "beta", + "description": "| ⚠️ This endpoint is currently in BETA |\n|--|\n\nReturns directly attached persons for a given Note.\n", + "summary": "Get Persons attached to a Note", + "operationId": "v2_notes_noteId_attached-persons__GET", + "tags": [ + "notes" ], - "additionalProperties": false, - "examples": [ - { - "code": "validation", - "param": "limit", - "message": "🚨 Error! Sound the alarm! 🚨" - } - ] - }, - "Error": { - "title": "Error", - "oneOf": [ - { - "$ref": "#/components/schemas/AuthenticationError" - }, - { - "$ref": "#/components/schemas/AuthorizationError" - }, - { - "$ref": "#/components/schemas/BadRequestError" - }, + "parameters": [ { - "$ref": "#/components/schemas/ConflictError" + "name": "noteId", + "description": "The id of the Note to get attached Persons", + "in": "path", + "required": true, + "schema": { + "type": "integer", + "format": "int32", + "minimum": 1, + "maximum": 2147483647 + } }, { - "$ref": "#/components/schemas/MethodNotAllowedError" + "name": "totalCount", + "description": "Include total count of the collection in the pagination response", + "in": "query", + "schema": { + "type": "boolean", + "default": false + } }, { - "$ref": "#/components/schemas/NotAcceptableError" + "name": "cursor", + "description": "Cursor for the next or previous page", + "in": "query", + "required": false, + "schema": { + "type": "string" + } }, { - "$ref": "#/components/schemas/NotFoundError" + "name": "limit", + "description": "Number of items to include in the page", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "format": "int32", + "minimum": 0, + "maximum": 100, + "default": 20 + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PersonDataPaged" + } + } + }, + "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" + } + } }, - { - "$ref": "#/components/schemas/NotImplementedError" + "400": { + "$ref": "#/components/responses/400" }, + "404": { + "$ref": "#/components/responses/404" + }, + "default": { + "$ref": "#/components/responses/default" + } + } + } + }, + "/v2/notes/{noteId}/replies": { + "get": { + "x-stability-level": "beta", + "description": "| ⚠️ This endpoint is currently in BETA |\n|--|\n\nThis endpoint returns reply notes for a given note id.\nYou can filter replies using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties.\n| **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** |\n|-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|---------------------------------|\n| `creator.id` | Filter notes by the creator of the note | `int32` | `=` | `creator.id=1` |\n| `createdAt` | Filter notes by when it was created | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-02-04T10:48:24Z` |\n| `updatedAt` | Filter notes by when it was updated | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-02-03T10:48:24Z`|\n", + "summary": "Get replies for a Note", + "operationId": "v2_notes_noteId_replies__GET", + "tags": [ + "notes" + ], + "parameters": [ { - "$ref": "#/components/schemas/RateLimitError" + "name": "noteId", + "description": "Note ID", + "in": "path", + "required": true, + "schema": { + "type": "integer", + "format": "int32", + "minimum": 1, + "maximum": 2147483647 + } }, { - "$ref": "#/components/schemas/ServerError" + "name": "filter", + "description": "Filter options", + "in": "query", + "schema": { + "type": "string" + } }, { - "$ref": "#/components/schemas/UnprocessableEntityError" + "name": "cursor", + "description": "Cursor for the next or previous page", + "in": "query", + "schema": { + "type": "string" + } }, { - "$ref": "#/components/schemas/UnsupportedMediaTypeError" + "name": "limit", + "description": "Number of items to include in the page", + "in": "query", + "schema": { + "type": "integer", + "format": "int32", + "minimum": 0, + "maximum": 100, + "default": 20 + } }, { - "$ref": "#/components/schemas/ValidationError" - } - ], - "discriminator": { - "propertyName": "code", - "mapping": { - "authentication": "#/components/schemas/AuthenticationError", - "authorization": "#/components/schemas/AuthorizationError", - "bad-request": "#/components/schemas/BadRequestError", - "conflict": "#/components/schemas/ConflictError", - "method-not-allowed": "#/components/schemas/MethodNotAllowedError", - "not-acceptable": "#/components/schemas/NotAcceptableError", - "not-found": "#/components/schemas/NotFoundError", - "not-implemented": "#/components/schemas/NotImplementedError", - "rate-limit": "#/components/schemas/RateLimitError", - "server": "#/components/schemas/ServerError", - "unprocessable-entity": "#/components/schemas/UnprocessableEntityError", - "unsupported-media-type": "#/components/schemas/UnsupportedMediaTypeError", - "validation": "#/components/schemas/ValidationError" - } - } - }, - "Errors": { - "title": "Errors", - "type": "object", - "properties": { - "errors": { - "description": "Errors", - "type": "array", - "items": { - "$ref": "#/components/schemas/Error" + "name": "totalCount", + "description": "Include total count of the collection in the pagination response", + "in": "query", + "schema": { + "type": "boolean", + "default": false } } - }, - "required": [ - "errors" ], - "additionalProperties": false - }, - "Tenant": { - "title": "Tenant", - "type": "object", - "properties": { - "id": { - "description": "The tenant's unique identifier", - "type": "integer", - "format": "int64", - "minimum": 1, - "maximum": 9007199254740991, - "examples": [ - 1 - ] + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/notes.RepliesPaged" + }, + "examples": { + "user-reply": { + "$ref": "#/components/examples/user-reply-2" + }, + "ai-notetaker-reply": { + "$ref": "#/components/examples/ai-notetaker-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" + } + } }, - "name": { - "description": "The name of the tenant", - "type": "string", - "examples": [ - "Contoso Ltd." - ] + "400": { + "$ref": "#/components/responses/400" }, - "subdomain": { - "description": "The tenant's subdomain under affinity.co", - "type": "string", - "format": "hostname", - "examples": [ - "contoso" - ] + "404": { + "$ref": "#/components/responses/404" + }, + "default": { + "$ref": "#/components/responses/default" } - }, - "required": [ - "id", - "name", - "subdomain" + } + } + }, + "/v2/opportunities": { + "get": { + "description": "Paginate through Opportunities in Affinity.\nReturns basic information but **not** field data on each Opportunity.\n\nTo access field data on Opportunities, use the `/lists/{list_id}/list-entries`\nor the `/v2/lists/{list_id}/saved-views/{view_id}/list-entries` GET endpoint.\n\nRequires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions).", + "summary": "Get all Opportunities", + "operationId": "v2_opportunities__GET", + "tags": [ + "opportunities" ], - "additionalProperties": false, - "examples": [ + "parameters": [ { - "name": "Contoso Ltd.", - "subdomain": "contoso", - "id": 1 - } - ] - }, - "User": { - "title": "User", - "type": "object", - "properties": { - "id": { - "description": "The user's unique identifier", - "type": "integer", - "format": "int64", - "minimum": 1, - "maximum": 9007199254740991, - "examples": [ - 1 - ] + "name": "cursor", + "description": "Cursor for the next or previous page", + "in": "query", + "schema": { + "type": "string", + "examples": [ + "ICAgICAgYmVmb3JlOjo6Nw" + ] + }, + "example": "ICAgICAgYmVmb3JlOjo6Nw" }, - "firstName": { - "description": "The user's first name", - "type": "string", - "examples": [ - "John" - ] + { + "name": "limit", + "description": "Number of items to include in the page", + "in": "query", + "schema": { + "type": "integer", + "format": "int32", + "minimum": 1, + "maximum": 100, + "default": 100, + "examples": [ + 100 + ] + }, + "example": 100 }, - "lastName": { - "description": "The user's last name", - "type": [ - "string", - "null" - ], - "examples": [ - "Smith" - ] - }, - "emailAddress": { - "description": "The user's email address", - "type": "string", - "format": "email", - "examples": [ - "john.smith@contoso.com" - ] - } - }, - "required": [ - "emailAddress", - "firstName", - "id", - "lastName" - ], - "additionalProperties": false, - "examples": [ { - "firstName": "John", - "lastName": "Smith", - "emailAddress": "john.smith@contoso.com", - "id": 1 - } - ] - }, - "Grant": { - "title": "Grant", - "type": "object", - "properties": { - "type": { - "description": "The type of grant used to authenticate", - "type": "string", - "const": "api-key", - "examples": [ - "api-key" - ] - }, - "scopes": { - "description": "The scopes available to the current grant", - "type": "array", - "items": { - "type": "string" + "name": "ids", + "description": "Opportunity IDs", + "in": "query", + "style": "form", + "explode": true, + "schema": { + "type": "array", + "items": { + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9223372036854776000 + } }, - "examples": [ - [ - "api" - ] - ] - }, - "createdAt": { - "description": "When the grant was created", - "type": "string", - "format": "date-time", - "examples": [ - "2023-01-01T00:00:00Z" + "example": [ + 1, + 2 ] } - }, - "required": [ - "createdAt", - "scopes", - "type" ], - "additionalProperties": false, - "examples": [ - { - "createdAt": "2023-01-01T00:00:00Z", - "scopes": [ - "api" - ], - "type": "api-key" - } - ] - }, - "WhoAmI": { - "title": "WhoAmI", - "description": "WhoAmI model", - "type": "object", - "properties": { - "tenant": { - "$ref": "#/components/schemas/Tenant" + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OpportunityPaged" + } + } + }, + "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" + } + } }, - "user": { - "$ref": "#/components/schemas/User" + "400": { + "$ref": "#/components/responses/400" }, - "grant": { - "$ref": "#/components/schemas/Grant" + "403": { + "$ref": "#/components/responses/403" + }, + "404": { + "$ref": "#/components/responses/404" + }, + "default": { + "$ref": "#/components/responses/default" } - }, - "required": [ - "grant", - "tenant", - "user" + } + } + }, + "/v2/opportunities/{opportunityId}": { + "get": { + "description": "Returns basic information but **not** field data on the requested Opportunity.\n\nTo access field data on Opportunities, use the `/lists/{list_id}/list-entries`\nor the `/v2/lists/{list_id}/saved-views/{view_id}/list-entries` GET endpoint.\n\nRequires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions).", + "summary": "Get a single Opportunity", + "operationId": "v2_opportunities_opportunityId__GET", + "tags": [ + "opportunities" ], - "additionalProperties": false, - "examples": [ + "parameters": [ { - "grant": { - "createdAt": "2023-01-01T00:00:00Z", - "scopes": [ - "api" - ], - "type": "api-key" - }, - "user": { - "firstName": "John", - "lastName": "Smith", - "emailAddress": "john.smith@contoso.com", - "id": 1 - }, - "tenant": { - "name": "Contoso Ltd.", - "subdomain": "contoso", - "id": 1 - } - } - ] - }, - "NotFoundErrors": { - "title": "NotFoundErrors", - "description": "NotFoundErrors model", - "type": "object", - "properties": { - "errors": { - "description": "NotFoundError errors", - "type": "array", - "items": { - "$ref": "#/components/schemas/NotFoundError" + "name": "opportunityId", + "description": "Opportunity ID", + "in": "path", + "required": true, + "schema": { + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9223372036854776000 } } - }, - "required": [ - "errors" ], - "additionalProperties": false, - "examples": [ - { - "errors": [ - { - "code": "not-found", - "message": "🚨 Error! Sound the alarm! 🚨" + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Opportunity" + } + } + }, + "headers": { + "X-Ratelimit-Limit-User": { + "$ref": "#/components/headers/X-Ratelimit-Limit-User" }, - { - "code": "not-found", - "message": "🚨 Error! Sound the alarm! 🚨" + "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" } - ] - } - ] - }, - "CompanyData": { - "title": "CompanyData", - "type": "object", - "properties": { - "id": { - "description": "The company's unique identifier", - "type": "integer", - "format": "int64", - "minimum": 1, - "maximum": 9007199254740991, - "examples": [ - 1 - ] + } }, - "name": { - "description": "The company's name", - "type": "string", - "examples": [ - "Acme" - ] + "400": { + "$ref": "#/components/responses/400" }, - "domain": { - "description": "The company's primary domain", - "type": [ - "string", - "null" - ], - "format": "hostname", - "examples": [ - "acme.co" - ] + "403": { + "$ref": "#/components/responses/403" + }, + "404": { + "$ref": "#/components/responses/404" + }, + "default": { + "$ref": "#/components/responses/default" } - }, - "required": [ - "domain", - "id", - "name" + } + } + }, + "/v2/opportunities/{opportunityId}/notes": { + "get": { + "x-stability-level": "beta", + "description": "| ⚠️ This endpoint is currently in BETA |\n|--|\n\nReturns Notes for a given Opportunity which includes directly attached notes and those attached to persons on this Opportunity.\n\nYou can filter notes using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties.\n| **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** |\n|-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|---------------------------------|\n| `creator.id` | Filter notes by the creator of the note | `int32` | `=` | `creator.id=1` |\n| `createdAt` | Filter notes by when it was created | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-02-04T10:48:24Z` |\n| `updatedAt` | Filter notes by when it was updated | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-02-03T10:48:24Z`|\n", + "summary": "Get Notes for an Opportunity", + "operationId": "v2_opportunities_opportunityId_notes__GET", + "tags": [ + "opportunities" ], - "additionalProperties": false - }, - "CompanyValue": { - "title": "CompanyValue", - "type": "object", - "properties": { - "type": { - "description": "The type of value", - "type": "string", - "const": "company" + "parameters": [ + { + "name": "opportunityId", + "description": "Opportunity ID", + "in": "path", + "required": true, + "schema": { + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9223372036854776000 + } }, - "data": { - "oneOf": [ - { - "$ref": "#/components/schemas/CompanyData" + { + "name": "filter", + "description": "Filter options", + "in": "query", + "schema": { + "type": "string" + } + }, + { + "name": "cursor", + "description": "Cursor for the next or previous page", + "in": "query", + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "description": "Number of items to include in the page", + "in": "query", + "schema": { + "type": "integer", + "format": "int32", + "minimum": 0, + "maximum": 100, + "default": 20 + } + }, + { + "name": "totalCount", + "description": "Include total count of the collection in the pagination response", + "in": "query", + "schema": { + "type": "boolean", + "default": false + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/notes.NotesPaged" + }, + "examples": { + "entities": { + "$ref": "#/components/examples/entities-3" + }, + "interaction": { + "$ref": "#/components/examples/interaction-4" + }, + "ai-notetaker": { + "$ref": "#/components/examples/ai-notetaker-3" + } + } + } + }, + "headers": { + "X-Ratelimit-Limit-User": { + "$ref": "#/components/headers/X-Ratelimit-Limit-User" }, - { - "type": "null" + "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" + }, + "404": { + "$ref": "#/components/responses/404" + }, + "default": { + "$ref": "#/components/responses/default" } - }, - "required": [ - "data", - "type" + } + } + }, + "/v2/person-merges": { + "get": { + "description": "Retrieve paginated person merges for the organization.\n\n\nReturns all person merges initiated by users in your organization, including their current\nstatus, the persons involved, and merge details. You can filter person merges using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties:\n\n\n| Property | Type | Operators | Values | Examples |\n|----------|------|-----------|--------|----------|\n| `status` | `enum` | `=` | `in-progress`, `success`, `failed` | `status=failed` |\n| `taskId` | `string` | `=` | | `taskId=789e0123-e45b-67c8-d901-234567890123` |\n\n\nPerson merges are returned in reverse chronological order (most recent first).\n\n\nRequires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and\norganization admin role.\n", + "summary": "Get All Person Merges", + "operationId": "v2_person-merges__GET", + "tags": [ + "personMerges" ], - "additionalProperties": false - }, - "CompaniesValue": { - "title": "CompaniesValue", - "type": "object", - "properties": { - "type": { - "description": "The type of value", - "type": "string", - "const": "company-multi" + "parameters": [ + { + "name": "cursor", + "description": "Cursor for the next or previous page", + "in": "query", + "schema": { + "type": "string" + }, + "example": "ICAgICAgYmVmb3JlOjo6Nw" }, - "data": { - "description": "The values for many companies", - "type": [ - "array", - "null" - ], - "items": { - "$ref": "#/components/schemas/CompanyData" + { + "name": "limit", + "description": "Number of items to include in the page", + "in": "query", + "schema": { + "type": "integer", + "format": "int32", + "minimum": 1, + "maximum": 100, + "default": 25 }, - "maxItems": 100 + "example": 25 + }, + { + "name": "filter", + "description": "Filter person merges using Affinity Filtering Language", + "in": "query", + "schema": { + "type": "string" + }, + "example": "status=failed | taskId=789e0123-e45b-67c8-d901-234567890123" } - }, - "required": [ - "data", - "type" ], - "additionalProperties": false - }, - "DateValue": { - "title": "DateValue", - "type": "object", - "properties": { - "type": { - "description": "The type of value", - "type": "string", - "const": "datetime" + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PersonMergeStatePaged" + }, + "examples": { + "merges-list": { + "$ref": "#/components/examples/merges-list-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" + } + } }, - "data": { - "description": "The value for a date", - "type": [ - "string", - "null" - ], - "format": "date-time" + "400": { + "$ref": "#/components/responses/400" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "default": { + "$ref": "#/components/responses/default" } - }, - "required": [ - "data", - "type" - ], - "additionalProperties": false + } }, - "Dropdown": { - "title": "Dropdown", - "type": "object", - "properties": { - "dropdownOptionId": { - "description": "Dropdown item's unique identifier", - "type": "integer", - "format": "int64", - "minimum": 1, - "maximum": 9007199254740991, - "examples": [ - 1 - ] - }, - "text": { - "description": "Dropdown item text", - "type": "string", - "examples": [ - "first" - ] - } - }, - "required": [ - "dropdownOptionId", - "text" + "post": { + "description": "Initiate a person merge to combine a duplicate person profile into a primary person profile.\n\nThis is an asynchronous process that will merge all data from the duplicate person into the primary person. Once the merge is initiated, you can track its progress using the returned [task URL](#tag/personMerges/operation/v2_tasks_person-merges_taskId__GET).\n\nRequires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role.", + "summary": "Initiate Person Merge", + "operationId": "v2_person-merges__POST", + "tags": [ + "personMerges" ], - "additionalProperties": false - }, - "DropdownValue": { - "title": "DropdownValue", - "type": "object", - "properties": { - "type": { - "description": "The type of value", - "type": "string", - "const": "dropdown" - }, - "data": { - "oneOf": [ - { - "$ref": "#/components/schemas/Dropdown" + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PersonMergeRequest" }, - { - "type": "null" + "examples": { + "merge-persons": { + "$ref": "#/components/examples/merge-persons" + } } - ] - } - }, - "required": [ - "data", - "type" - ], - "additionalProperties": false - }, - "DropdownsValue": { - "title": "DropdownsValue", - "type": "object", - "properties": { - "type": { - "description": "The type of value", - "type": "string", - "const": "dropdown-multi" - }, - "data": { - "description": "The value for many dropdown items", - "type": [ - "array", - "null" - ], - "items": { - "$ref": "#/components/schemas/Dropdown" } } }, - "required": [ - "data", - "type" - ], - "additionalProperties": false - }, - "FloatValue": { - "title": "FloatValue", - "type": "object", - "properties": { - "type": { - "description": "The type of value", - "type": "string", - "const": "number" + "responses": { + "202": { + "description": "Accepted", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PersonMergeResponse" + }, + "examples": { + "merge-initiated": { + "$ref": "#/components/examples/merge-initiated-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" + } + } }, - "data": { - "description": "The value for a number", - "type": [ - "number", - "null" - ] + "400": { + "$ref": "#/components/responses/400" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "default": { + "$ref": "#/components/responses/default" } - }, - "required": [ - "data", - "type" + } + } + }, + "/v2/person-merges/{mergeId}": { + "get": { + "description": "Retrieve the status and details of a specific person merge.\n\nReturns information about the person merge including its current status, the persons involved, timestamps, and any error information if the merge failed.\n\nThe `mergeId` can be obtained from the response of the [Get All Person Merges](#tag/personMerges/operation/v2_person-merges__GET) endpoint, or by filtering person merges by task ID using `/v2/person-merges?filter=taskId={taskId}` after initiating a merge.\n\nRequires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role.", + "summary": "Get Person Merge", + "operationId": "v2_person-merges_mergeId__GET", + "tags": [ + "personMerges" ], - "additionalProperties": false - }, - "FloatsValue": { - "title": "FloatsValue", - "type": "object", - "properties": { - "type": { - "description": "The type of value", - "type": "string", - "const": "number-multi" - }, - "data": { - "description": "The value for many numbers", - "type": [ - "array", - "null" - ], - "items": { - "type": "number" + "parameters": [ + { + "name": "mergeId", + "description": "Person merge ID", + "in": "path", + "required": true, + "schema": { + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 12345 + ] } } - }, - "required": [ - "data", - "type" ], - "additionalProperties": false - }, - "TextValue": { - "title": "TextValue", - "type": "object", - "properties": { - "type": { - "description": "The type of value", - "type": "string", - "enum": [ - "filterable-text", - "text" - ], - "examples": [ - "filterable-text" - ] + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PersonMergeState" + }, + "examples": { + "completed-merge": { + "$ref": "#/components/examples/succeeded-merge-2" + }, + "failed-merge": { + "$ref": "#/components/examples/failed-merge-2" + }, + "in-progress-merge": { + "$ref": "#/components/examples/in-progress-merge-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" + } + } }, - "data": { - "description": "The value for a string", - "type": [ - "string", - "null" - ] + "400": { + "$ref": "#/components/responses/400" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "404": { + "$ref": "#/components/responses/404" + }, + "default": { + "$ref": "#/components/responses/default" } - }, - "required": [ - "data", - "type" + } + } + }, + "/v2/persons": { + "get": { + "description": "Paginate through Persons in Affinity.\nReturns basic information and non-list-specific field data on each Person.\n\nTo retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter\nto specify the Fields for which you want data returned.\nThese Field IDs and Types can be found using the GET `/v2/persons/fields` endpoint.\nWhen no `fieldIds` or `fieldTypes` are provided, Persons will be returned without any field data attached.\nTo supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this:\n`?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`.\n\nRequires the \"Export All People directory\" [permission](#section/Getting-Started/Permissions).", + "summary": "Get all Persons", + "operationId": "v2_persons__GET", + "tags": [ + "persons" ], - "additionalProperties": false - }, - "TextsValue": { - "title": "TextsValue", - "type": "object", - "properties": { - "type": { - "description": "The type of value", - "type": "string", - "const": "filterable-text-multi" + "parameters": [ + { + "name": "cursor", + "description": "Cursor for the next or previous page", + "in": "query", + "schema": { + "type": "string", + "examples": [ + "ICAgICAgYmVmb3JlOjo6Nw" + ] + }, + "example": "ICAgICAgYmVmb3JlOjo6Nw" }, - "data": { - "description": "The value for many strings", - "type": [ - "array", - "null" - ], - "items": { - "type": "string" - } - } - }, - "required": [ - "data", - "type" - ], - "additionalProperties": false - }, - "FormulaNumber": { - "title": "FormulaNumber", - "type": "object", - "properties": { - "calculatedValue": { - "description": "Calculated value", - "type": [ - "number", - "null" + { + "name": "limit", + "description": "Number of items to include in the page", + "in": "query", + "schema": { + "type": "integer", + "format": "int32", + "minimum": 1, + "maximum": 100, + "default": 100, + "examples": [ + 100 + ] + }, + "example": 100 + }, + { + "name": "ids", + "description": "People IDs", + "in": "query", + "style": "form", + "explode": true, + "schema": { + "type": "array", + "items": { + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9223372036854776000 + } + }, + "example": [ + 1, + 2 ] - } - }, - "additionalProperties": false - }, - "FormulaValue": { - "title": "FormulaValue", - "type": "object", - "properties": { - "type": { - "description": "The type of value", - "type": "string", - "const": "formula-number" }, - "data": { - "oneOf": [ - { - "$ref": "#/components/schemas/FormulaNumber" + { + "name": "fieldIds", + "description": "Field IDs for which to return field data", + "in": "query", + "style": "form", + "explode": true, + "schema": { + "type": "array", + "items": { + "type": "string" }, - { - "type": "null" + "examples": [ + [ + "field-1" + ] + ] + }, + "example": [ + "field-1", + "field-2" + ] + }, + { + "name": "fieldTypes", + "description": "Field Types for which to return field data", + "in": "query", + "style": "form", + "explode": true, + "schema": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "enriched", + "global", + "relationship-intelligence" + ] } + }, + "example": [ + "enriched", + "global" ] } - }, - "required": [ - "data", - "type" ], - "additionalProperties": false - }, - "PersonData": { - "title": "PersonData", - "type": "object", - "properties": { - "id": { - "description": "The persons's unique identifier", - "type": "integer", - "format": "int64", - "minimum": 1, - "maximum": 9007199254740991, - "examples": [ - 1 - ] - }, - "firstName": { - "description": "The person's first name", - "type": [ - "string", - "null" - ], - "examples": [ - "Jane" - ] + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PersonPaged" + } + } + }, + "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" + } + } }, - "lastName": { - "description": "The person's last name", - "type": [ - "string", - "null" - ], - "examples": [ - "Doe" - ] + "400": { + "$ref": "#/components/responses/400" }, - "primaryEmailAddress": { - "description": "The person's primary email address", - "type": [ - "string", - "null" - ], - "format": "email", - "examples": [ - "jane.doe@acme.co" - ] + "403": { + "$ref": "#/components/responses/403" }, - "type": { - "description": "The person's type", - "type": "string", - "enum": [ - "internal", - "external", - "collaborator" - ], - "examples": [ - "internal" - ] + "default": { + "$ref": "#/components/responses/default" } - }, - "required": [ - "firstName", - "id", - "lastName", - "primaryEmailAddress", - "type" + } + } + }, + "/v2/persons/fields": { + "get": { + "description": "Returns metadata on non-list-specific Person Fields.\n\nUse the returned Field IDs to request field data from the GET `/v2/persons` and GET `/v2/persons/{id}` endpoints.", + "summary": "Get metadata on Person Fields", + "operationId": "v2_persons_fields__GET", + "tags": [ + "persons" ], - "additionalProperties": false - }, - "ChatMessage": { - "title": "ChatMessage", - "type": "object", - "properties": { - "type": { - "description": "The type of interaction", - "type": "string", - "const": "chat-message", - "examples": [ - "chat-message" - ] - }, - "id": { - "description": "The chat message's unique identifier", - "type": "integer", - "format": "int64", - "minimum": 1, - "maximum": 9007199254740991, - "examples": [ - 1 - ] - }, - "direction": { - "description": "The direction of the chat message", - "type": "string", - "enum": [ - "received", - "sent" - ], - "examples": [ - "outbound" - ] - }, - "sentAt": { - "description": "The time the chat message was sent", - "type": "string", - "format": "date-time", - "examples": [ - "2023-01-01T00:00:00Z" - ] - }, - "manualCreator": { - "$ref": "#/components/schemas/PersonData" - }, - "participants": { - "description": "The participants of the chat", - "type": "array", - "items": { - "$ref": "#/components/schemas/PersonData" + "parameters": [ + { + "name": "cursor", + "description": "Cursor for the next or previous page", + "in": "query", + "schema": { + "type": "string" } + }, + { + "name": "limit", + "description": "Number of items to include in the page", + "in": "query", + "schema": { + "type": "integer", + "format": "int32", + "minimum": 1, + "maximum": 100, + "default": 100, + "examples": [ + 100 + ] + }, + "example": 100 } - }, - "required": [ - "direction", - "id", - "manualCreator", - "participants", - "sentAt", - "type" ], - "additionalProperties": false - }, - "Attendee": { - "title": "Attendee", - "type": "object", - "properties": { - "emailAddress": { - "description": "The email addresses of the attendee", - "type": [ - "string", - "null" - ], - "format": "email", - "examples": [ - "john.smith@contoso.com" - ] - }, - "person": { - "oneOf": [ - { - "$ref": "#/components/schemas/PersonData" + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FieldMetadataPaged" + } + } + }, + "headers": { + "X-Ratelimit-Limit-User": { + "$ref": "#/components/headers/X-Ratelimit-Limit-User" }, - { - "type": "null" + "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" + }, + "default": { + "$ref": "#/components/responses/default" } - }, - "required": [ - "emailAddress", - "person" + } + } + }, + "/v2/persons/{personId}": { + "get": { + "description": "Returns basic information and non-list-specific field data on the requested Person.\n\nTo retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter\nto specify the Fields for which you want data returned.\nThese Field IDs and Types can be found using the GET `/v2/persons/fields` endpoint.\nWhen no `fieldIds` or `fieldTypes` are provided, Persons will be returned without any field data attached.\nTo supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this:\n`?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`.\n\nRequires the \"Export All People directory\" [permission](#section/Getting-Started/Permissions).", + "summary": "Get a single Person", + "operationId": "v2_persons_personId__GET", + "tags": [ + "persons" ], - "additionalProperties": false - }, - "Email": { - "title": "Email", - "type": "object", - "properties": { - "type": { - "description": "The type of interaction", - "type": "string", - "const": "email", - "examples": [ - "email" - ] + "parameters": [ + { + "name": "personId", + "description": "Person ID", + "in": "path", + "required": true, + "schema": { + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9223372036854776000 + } }, - "id": { - "description": "The email's unique identifier", - "type": "integer", - "format": "int64", - "minimum": 1, - "maximum": 9007199254740991, - "examples": [ - 1 + { + "name": "fieldIds", + "description": "Field IDs for which to return field data", + "in": "query", + "style": "form", + "explode": true, + "schema": { + "type": "array", + "items": { + "type": "string" + }, + "examples": [ + [ + "field-1" + ] + ] + }, + "example": [ + "field-1", + "field-2" ] }, - "subject": { - "description": "The subject of the email", - "type": [ - "string", - "null" - ], - "examples": [ - "Acme Upsell $10k" + { + "name": "fieldTypes", + "description": "Field Types for which to return field data", + "in": "query", + "style": "form", + "explode": true, + "schema": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "enriched", + "global", + "relationship-intelligence" + ] + } + }, + "example": [ + "enriched", + "global" ] + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Person" + } + } + }, + "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" + } + } }, - "sentAt": { - "description": "The time the email was sent", - "type": "string", - "format": "date-time", - "examples": [ - "2023-01-01T00:00:00Z" - ] + "400": { + "$ref": "#/components/responses/400" }, - "from": { - "$ref": "#/components/schemas/Attendee" + "403": { + "$ref": "#/components/responses/403" }, - "to": { - "description": "The recipients of the email", - "type": "array", - "items": { - "$ref": "#/components/schemas/Attendee" - } + "404": { + "$ref": "#/components/responses/404" }, - "cc": { - "description": "The cc recipients of the email", - "type": "array", - "items": { - "$ref": "#/components/schemas/Attendee" - } + "default": { + "$ref": "#/components/responses/default" } - }, - "required": [ - "cc", - "from", - "id", - "sentAt", - "subject", - "to", - "type" + } + } + }, + "/v2/persons/{personId}/list-entries": { + "get": { + "description": "Paginate through the List Entries (AKA rows) for the given Person across all Lists.\nEach List Entry includes field data for the Person, including list-specific field data.\nEach List Entry also includes metadata about its creation, i.e., when it was added to the List and by whom.\n\nRequires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions).", + "summary": "Get a Person's List Entries", + "operationId": "v2_persons_personId_list-entries__GET", + "tags": [ + "persons" ], - "additionalProperties": false - }, - "Meeting": { - "title": "Meeting", - "type": "object", - "properties": { - "type": { - "description": "The type of interaction", - "type": "string", - "const": "meeting", - "examples": [ - "meeting" - ] - }, - "id": { - "description": "The meeting's unique identifier", - "type": "integer", - "format": "int64", - "minimum": 1, - "maximum": 9007199254740991, - "examples": [ - 1 - ] - }, - "title": { - "description": "The meeting's title", - "type": [ - "string", - "null" - ], - "examples": [ - "Acme Upsell $10k" - ] - }, - "allDay": { - "description": "Whether the meeting is an all-day event", - "type": "boolean", - "examples": [ - false - ] - }, - "startTime": { - "description": "The meeting start time", - "type": "string", - "format": "date-time", - "examples": [ - "2023-02-03T04:00:00Z" - ] + "parameters": [ + { + "name": "personId", + "description": "Persons ID", + "in": "path", + "required": true, + "schema": { + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9223372036854776000 + } }, - "endTime": { - "description": "The meeting end time", - "type": [ - "string", - "null" - ], - "format": "date-time", - "examples": [ - "2023-02-03T05:00:00Z" - ] + { + "name": "cursor", + "description": "Cursor for the next or previous page", + "in": "query", + "schema": { + "type": "string", + "examples": [ + "ICAgICAgYmVmb3JlOjo6Nw" + ] + }, + "example": "ICAgICAgYmVmb3JlOjo6Nw" }, - "attendees": { - "description": "People attending the meeting", - "type": "array", - "items": { - "$ref": "#/components/schemas/Attendee" - } + { + "name": "limit", + "description": "Number of items to include in the page", + "in": "query", + "schema": { + "type": "integer", + "format": "int32", + "minimum": 1, + "maximum": 100, + "default": 100, + "examples": [ + 100 + ] + }, + "example": 100 } - }, - "required": [ - "allDay", - "attendees", - "endTime", - "id", - "startTime", - "title", - "type" ], - "additionalProperties": false - }, - "PhoneCall": { - "title": "PhoneCall", - "type": "object", - "properties": { - "type": { - "description": "The type of interaction", - "type": "string", - "const": "call", - "examples": [ - "call" - ] + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListEntryPaged" + } + } + }, + "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" + } + } }, - "id": { - "description": "The phon_call's unique identifier", - "type": "integer", - "format": "int64", - "minimum": 1, - "maximum": 9007199254740991, - "examples": [ - 1 - ] + "400": { + "$ref": "#/components/responses/400" }, - "startTime": { - "description": "The call start time", - "type": "string", - "format": "date-time", - "examples": [ - "2023-02-03T04:00:00Z" - ] + "403": { + "$ref": "#/components/responses/403" }, - "attendees": { - "description": "People attending the call", - "type": "array", - "items": { - "$ref": "#/components/schemas/Attendee" - } + "404": { + "$ref": "#/components/responses/404" + }, + "default": { + "$ref": "#/components/responses/default" } - }, - "required": [ - "attendees", - "id", - "startTime", - "type" + } + } + }, + "/v2/persons/{personId}/lists": { + "get": { + "description": "Paginate through all Lists where the given Person appears as an entry and that you have access to view.\nReturns basic List information for each List that contains this Person.", + "summary": "Get a Person's Lists", + "operationId": "v2_persons_personId_lists__GET", + "tags": [ + "persons" ], - "additionalProperties": false - }, - "Interaction": { - "title": "Interaction", - "oneOf": [ - { - "$ref": "#/components/schemas/ChatMessage" - }, + "parameters": [ { - "$ref": "#/components/schemas/Email" + "name": "personId", + "description": "Persons ID", + "in": "path", + "required": true, + "schema": { + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9223372036854776000 + } }, { - "$ref": "#/components/schemas/Meeting" + "name": "cursor", + "description": "Cursor for the next or previous page", + "in": "query", + "schema": { + "type": "string", + "examples": [ + "ICAgICAgYmVmb3JlOjo6Nw" + ] + }, + "example": "ICAgICAgYmVmb3JlOjo6Nw" }, { - "$ref": "#/components/schemas/PhoneCall" - } - ], - "discriminator": { - "propertyName": "type", - "mapping": { - "chat-message": "#/components/schemas/ChatMessage", - "email": "#/components/schemas/Email", - "meeting": "#/components/schemas/Meeting", - "call": "#/components/schemas/PhoneCall" + "name": "limit", + "description": "Number of items to include in the page", + "in": "query", + "schema": { + "type": "integer", + "format": "int32", + "minimum": 1, + "maximum": 100, + "default": 100, + "examples": [ + 100 + ] + }, + "example": 100 } - } - }, - "InteractionValue": { - "title": "InteractionValue", - "type": "object", - "properties": { - "type": { - "description": "The type of value", - "type": "string", - "const": "interaction" - }, - "data": { - "oneOf": [ - { - "$ref": "#/components/schemas/Interaction" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListPaged" + } + } + }, + "headers": { + "X-Ratelimit-Limit-User": { + "$ref": "#/components/headers/X-Ratelimit-Limit-User" }, - { - "type": "null" + "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" } - ] - } - }, - "required": [ - "data", - "type" - ], - "additionalProperties": false - }, - "Location": { - "title": "Location", - "type": "object", - "properties": { - "streetAddress": { - "description": "Street address", - "type": [ - "string", - "null" - ], - "examples": [ - "170 Columbus Ave" - ] - }, - "city": { - "description": "City", - "type": [ - "string", - "null" - ], - "examples": [ - "San Francisco" - ] + } }, - "state": { - "description": "State", - "type": [ - "string", - "null" - ], - "examples": [ - "California" - ] + "400": { + "$ref": "#/components/responses/400" }, - "country": { - "description": "Country", - "type": [ - "string", - "null" - ], - "examples": [ - "United States" - ] + "404": { + "$ref": "#/components/responses/404" }, - "continent": { - "description": "Continent", - "type": [ - "string", - "null" - ], - "examples": [ - "North America" - ] + "default": { + "$ref": "#/components/responses/default" } - }, - "required": [ - "city", - "continent", - "country", - "state", - "streetAddress" + } + } + }, + "/v2/persons/{personId}/notes": { + "get": { + "x-stability-level": "beta", + "description": "| ⚠️ This endpoint is currently in BETA |\n|--|\n\nReturns notes for a given person id which includes directly attached notes, notes on meetings this person attended, and notes where this person is mentioned.\n\nYou can filter notes using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties.\n| **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** |\n|-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|---------------------------------|\n| `creator.id` | Filter notes by the creator of the note | `int32` | `=` | `creator.id=1` |\n| `createdAt` | Filter notes by when it was created | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-02-04T10:48:24Z` |\n| `updatedAt` | Filter notes by when it was updated | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-02-03T10:48:24Z`|\n", + "summary": "Get Notes for a Person", + "operationId": "v2_persons_personId_notes__GET", + "tags": [ + "persons" ], - "additionalProperties": false, - "examples": [ + "parameters": [ { - "continent": "North America", - "country": "United States", - "streetAddress": "170 Columbus Ave", - "city": "San Francisco", - "state": "California" - } - ] - }, - "LocationValue": { - "title": "LocationValue", - "type": "object", - "properties": { - "type": { - "description": "The type of value", - "type": "string", - "const": "location" + "name": "personId", + "description": "Persons ID", + "in": "path", + "required": true, + "schema": { + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9223372036854776000 + } }, - "data": { - "oneOf": [ - { - "$ref": "#/components/schemas/Location" - }, - { - "type": "null" - } - ] - } - }, - "required": [ - "data", - "type" - ], - "additionalProperties": false - }, - "LocationsValue": { - "title": "LocationsValue", - "type": "object", - "properties": { - "type": { - "description": "The type of value", - "type": "string", - "const": "location-multi" + { + "name": "filter", + "description": "Filter options", + "in": "query", + "schema": { + "type": "string" + } }, - "data": { - "description": "The values for many locations", - "type": [ - "array", - "null" - ], - "items": { - "$ref": "#/components/schemas/Location" + { + "name": "cursor", + "description": "Cursor for the next or previous page", + "in": "query", + "schema": { + "type": "string" } - } - }, - "required": [ - "data", - "type" - ], - "additionalProperties": false - }, - "PersonValue": { - "title": "PersonValue", - "type": "object", - "properties": { - "type": { - "description": "The type of value", - "type": "string", - "const": "person" }, - "data": { - "oneOf": [ - { - "$ref": "#/components/schemas/PersonData" - }, - { - "type": "null" - } - ] + { + "name": "limit", + "description": "Number of items to include in the page", + "in": "query", + "schema": { + "type": "integer", + "format": "int32", + "minimum": 0, + "maximum": 100, + "default": 20 + } + }, + { + "name": "totalCount", + "description": "Include total count of the collection in the pagination response", + "in": "query", + "schema": { + "type": "boolean", + "default": false + } } - }, - "required": [ - "data", - "type" ], - "additionalProperties": false - }, - "PersonsValue": { - "title": "PersonsValue", - "type": "object", - "properties": { - "type": { - "description": "The type of value", - "type": "string", - "const": "person-multi" - }, - "data": { - "description": "The values for many persons", - "type": [ - "array", - "null" - ], - "items": { - "$ref": "#/components/schemas/PersonData" + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/notes.NotesPaged" + }, + "examples": { + "entities": { + "$ref": "#/components/examples/entities-3" + }, + "interaction": { + "$ref": "#/components/examples/interaction-4" + }, + "ai-notetaker": { + "$ref": "#/components/examples/ai-notetaker-3" + } + } + } }, - "maxItems": 100 - } - }, - "required": [ - "data", - "type" - ], - "additionalProperties": false - }, - "RankedDropdown": { - "title": "RankedDropdown", - "type": "object", - "properties": { - "dropdownOptionId": { - "description": "Dropdown item's unique identifier", - "type": "integer", - "format": "int64", - "minimum": 1, - "maximum": 9007199254740991, - "examples": [ - 1 - ] - }, - "text": { - "description": "Dropdown item text", - "type": "string", - "examples": [ - "first" - ] - }, - "rank": { - "description": "Dropdown item rank", - "type": "integer", - "format": "int64", - "minimum": 0, - "maximum": 9007199254740991, - "examples": [ - 0 - ] - }, - "color": { - "description": "Dropdown item color", - "type": [ - "string", - "null" - ], - "examples": [ - "white" - ] - } - }, - "required": [ - "color", - "dropdownOptionId", - "rank", - "text" - ], - "additionalProperties": false - }, - "RankedDropdownValue": { - "title": "RankedDropdownValue", - "type": "object", - "properties": { - "type": { - "description": "The type of value", - "type": "string", - "const": "ranked-dropdown" - }, - "data": { - "oneOf": [ - { - "$ref": "#/components/schemas/RankedDropdown" + "headers": { + "X-Ratelimit-Limit-User": { + "$ref": "#/components/headers/X-Ratelimit-Limit-User" }, - { - "type": "null" + "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" } - ] - } - }, - "required": [ - "data", - "type" - ], - "additionalProperties": false - }, - "FieldValue": { - "title": "FieldValue", - "oneOf": [ - { - "$ref": "#/components/schemas/CompaniesValue" - }, - { - "$ref": "#/components/schemas/CompanyValue" - }, - { - "$ref": "#/components/schemas/DateValue" - }, - { - "$ref": "#/components/schemas/DropdownsValue" - }, - { - "$ref": "#/components/schemas/DropdownValue" - }, - { - "$ref": "#/components/schemas/FloatsValue" - }, - { - "$ref": "#/components/schemas/FloatValue" - }, - { - "$ref": "#/components/schemas/FormulaValue" + } }, - { - "$ref": "#/components/schemas/InteractionValue" + "400": { + "$ref": "#/components/responses/400" }, - { - "$ref": "#/components/schemas/LocationsValue" + "404": { + "$ref": "#/components/responses/404" }, + "default": { + "$ref": "#/components/responses/default" + } + } + } + }, + "/v2/tasks/company-merges": { + "get": { + "description": "Retrieve paginated company merge tasks for the organization.\n\n\nReturns all merge tasks initiated by users in your organization, including their current status,\nthe companies involved, and task details.\n\n\nYou can filter tasks using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties:\n\n| Property | Type | Operators | Values | Examples |\n|----------|------|-----------|--------|----------|\n| `status` | `enum` | `=` | `in-progress`, `success`, `failed` | `status=failed` |\n\n\nTasks are returned in reverse chronological order (most recent first).\n\n\nRequires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and\norganization admin role.\n", + "summary": "Get All Company Merge Tasks", + "operationId": "v2_tasks_company-merges__GET", + "tags": [ + "companyMerges" + ], + "parameters": [ { - "$ref": "#/components/schemas/LocationValue" + "name": "cursor", + "description": "Cursor for the next or previous page", + "in": "query", + "schema": { + "type": "string", + "examples": [ + "ICAgICAgYmVmb3JlOjo6Nw" + ] + }, + "example": "ICAgICAgYmVmb3JlOjo6Nw" }, { - "$ref": "#/components/schemas/PersonsValue" + "name": "limit", + "description": "Number of items to include in the page", + "in": "query", + "schema": { + "type": "integer", + "format": "int32", + "minimum": 1, + "maximum": 100, + "default": 100 + }, + "example": 100 }, { - "$ref": "#/components/schemas/PersonValue" + "name": "filter", + "description": "Filter tasks using Affinity Filtering Language", + "in": "query", + "schema": { + "type": "string" + }, + "example": "status=failed" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CompanyMergeTaskPaged" + }, + "examples": { + "tasks-list": { + "$ref": "#/components/examples/tasks-list" + } + } + } + }, + "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" + } + } }, - { - "$ref": "#/components/schemas/RankedDropdownValue" + "400": { + "$ref": "#/components/responses/400" }, - { - "$ref": "#/components/schemas/TextsValue" + "403": { + "$ref": "#/components/responses/403" }, - { - "$ref": "#/components/schemas/TextValue" + "default": { + "$ref": "#/components/responses/default" } + } + } + }, + "/v2/tasks/company-merges/{taskId}": { + "get": { + "description": "Retrieve the status and details of a specific task for company merges.\n\n\nReturns information about the company merges for a specific task including its overall status,\nnumber of merges in-progress, completed, and failed.\n\n\nDetailed information about individual merges for this task can be found by querying:\n`/v2/company-merges?filter=taskId={taskId}` See [Company\nMerges](#tag/companyMerges/operation/v2_company-merges__GET) for more details.\n\n\nTask statuses:\n\n- `in-progress`: The merge task is currently being processed.\n- `success`: The merge task completed successfully.\n- `failed`: The merge task failed.\n\n\nRequires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and\norganization admin role.\n", + "summary": "Get Company Merge Task", + "operationId": "v2_tasks_company-merges_taskId__GET", + "tags": [ + "companyMerges" ], - "discriminator": { - "propertyName": "type", - "mapping": { - "company": "#/components/schemas/CompanyValue", - "company-multi": "#/components/schemas/CompaniesValue", - "datetime": "#/components/schemas/DateValue", - "dropdown": "#/components/schemas/DropdownValue", - "dropdown-multi": "#/components/schemas/DropdownsValue", - "number": "#/components/schemas/FloatValue", - "number-multi": "#/components/schemas/FloatsValue", - "filterable-text": "#/components/schemas/TextValue", - "filterable-text-multi": "#/components/schemas/TextsValue", - "formula-number": "#/components/schemas/FormulaValue", - "interaction": "#/components/schemas/InteractionValue", - "location": "#/components/schemas/LocationValue", - "location-multi": "#/components/schemas/LocationsValue", - "person": "#/components/schemas/PersonValue", - "person-multi": "#/components/schemas/PersonsValue", - "ranked-dropdown": "#/components/schemas/RankedDropdownValue", - "text": "#/components/schemas/TextValue" - } - }, - "examples": [ + "parameters": [ { - "data": { - "continent": "North America", - "country": "United States", - "streetAddress": "170 Columbus Ave", - "city": "San Francisco", - "state": "California" - }, - "type": "location" + "name": "taskId", + "description": "Company merge task ID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid", + "examples": [ + "123e4567-e89b-12d3-a456-426614174000" + ] + } } - ] - }, - "Field": { - "title": "Field", - "type": "object", - "properties": { - "id": { - "description": "The field's unique identifier", - "type": "string", - "examples": [ - "affinity-data-location" - ] + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CompanyMergeTask" + }, + "examples": { + "task-in-progress": { + "$ref": "#/components/examples/task-in-progress" + }, + "task-success": { + "$ref": "#/components/examples/task-success" + }, + "task-failed": { + "$ref": "#/components/examples/task-failed" + } + } + } + }, + "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" + } + } }, - "name": { - "description": "The field's name", - "type": "string", - "examples": [ - "Location" - ] + "400": { + "$ref": "#/components/responses/400" }, - "type": { - "description": "The field's type", - "type": "string", - "enum": [ - "enriched", - "global", - "list", - "relationship-intelligence" - ], - "examples": [ - "enriched" - ] + "403": { + "$ref": "#/components/responses/403" }, - "enrichmentSource": { - "description": "The source of the data in this Field (if it is enriched)", - "type": [ - "string", - "null" - ], - "enum": [ - "affinity-data", - "dealroom", - null - ], - "examples": [ - "affinity-data" - ] + "404": { + "$ref": "#/components/responses/404" }, - "value": { - "$ref": "#/components/schemas/FieldValue" + "default": { + "$ref": "#/components/responses/default" } - }, - "required": [ - "enrichmentSource", - "id", - "name", - "type", - "value" + } + } + }, + "/v2/tasks/person-merges": { + "get": { + "description": "Retrieve paginated person merge tasks for the organization.\n\n\nReturns all merge tasks initiated by users in your organization, including their current status,\nthe persons involved, and task details.\n\n\nYou can filter tasks using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties:\n\n| Property | Type | Operators | Values | Examples |\n|----------|------|-----------|--------|----------|\n| `status` | `enum` | `=` | `in-progress`, `success`, `failed` | `status=failed` |\n\n\nTasks are returned in reverse chronological order (most recent first).\n\n\nRequires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and\norganization admin role.\n", + "summary": "Get All Person Merge Tasks", + "operationId": "v2_tasks_person-merges__GET", + "tags": [ + "personMerges" ], - "additionalProperties": false, - "examples": [ + "parameters": [ { - "enrichmentSource": "affinity-data", - "name": "Location", - "id": "affinity-data-location", - "type": "enriched", - "value": { - "data": { - "continent": "North America", - "country": "United States", - "streetAddress": "170 Columbus Ave", - "city": "San Francisco", - "state": "California" - }, - "type": "location" - } - } - ] - }, - "Company": { - "title": "Company", - "description": "Company model", - "type": "object", - "properties": { - "id": { - "description": "The company's unique identifier", - "type": "integer", - "format": "int64", - "minimum": 1, - "maximum": 9007199254740991, - "examples": [ - 1 - ] - }, - "name": { - "description": "The company's name", - "type": "string", - "examples": [ - "Acme" - ] - }, - "domain": { - "description": "The company's primary domain", - "type": [ - "string", - "null" - ], - "format": "hostname", - "examples": [ - "acme.co" - ] - }, - "domains": { - "description": "All of the company's domains", - "type": "array", - "items": { + "name": "cursor", + "description": "Cursor for the next or previous page", + "in": "query", + "schema": { "type": "string", - "format": "hostname" - }, - "examples": [ - [ - "acme.co" + "examples": [ + "ICAgICAgYmVmb3JlOjo6Nw" ] - ] + }, + "example": "ICAgICAgYmVmb3JlOjo6Nw" }, - "isGlobal": { - "description": "Whether or not the company is tenant specific", - "type": "boolean", - "examples": [ - true - ] + { + "name": "limit", + "description": "Number of items to include in the page", + "in": "query", + "schema": { + "type": "integer", + "format": "int32", + "minimum": 1, + "maximum": 100, + "default": 25, + "examples": [ + 25 + ] + }, + "example": 25 }, - "fields": { - "description": "The fields associated with the company", - "type": "array", - "items": { - "$ref": "#/components/schemas/Field" - } + { + "name": "filter", + "description": "Filter tasks using Affinity Filtering Language", + "in": "query", + "schema": { + "type": "string" + }, + "example": "status=failed" } - }, - "required": [ - "domain", - "domains", - "id", - "isGlobal", - "name" ], - "additionalProperties": false, - "examples": [ - { - "domain": "acme.co", - "name": "Acme", - "isGlobal": true, - "domains": [ - "acme.co" - ], - "id": 1, - "fields": [ - { - "enrichmentSource": "affinity-data", - "name": "Location", - "id": "affinity-data-location", - "type": "enriched", - "value": { - "data": { - "continent": "North America", - "country": "United States", - "streetAddress": "170 Columbus Ave", - "city": "San Francisco", - "state": "California" - }, - "type": "location" + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PersonMergeTaskPaged" + }, + "examples": { + "tasks-list": { + "$ref": "#/components/examples/tasks-list-2" + } } + } + }, + "headers": { + "X-Ratelimit-Limit-User": { + "$ref": "#/components/headers/X-Ratelimit-Limit-User" }, - { - "enrichmentSource": "affinity-data", - "name": "Location", - "id": "affinity-data-location", - "type": "enriched", - "value": { - "data": { - "continent": "North America", - "country": "United States", - "streetAddress": "170 Columbus Ave", - "city": "San Francisco", - "state": "California" + "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" + }, + "default": { + "$ref": "#/components/responses/default" + } + } + } + }, + "/v2/tasks/person-merges/{taskId}": { + "get": { + "description": "Retrieve the status and details of a specific task for person merges.\n\n\nReturns information about the person merges for a specific task including its overall status,\nnumber of merges in-progress, completed, and failed.\n\n\nDetailed information about individual merges for this task can be found by querying:\n`/v2/person-merges?filter=taskId={taskId}` See [Person\nMerges](#tag/personMerges/operation/v2_person-merges__GET) for more details.\n\n\nTask statuses:\n\n- `in-progress`: The merge task is currently being processed.\n- `success`: The merge task completed successfully.\n- `failed`: The merge task failed.\n\n\nRequires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and\norganization admin role.\n", + "summary": "Get Person Merge Task", + "operationId": "v2_tasks_person-merges_taskId__GET", + "tags": [ + "personMerges" + ], + "parameters": [ + { + "name": "taskId", + "description": "Person merge task ID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid", + "examples": [ + "123e4567-e89b-12d3-a456-426614174000" + ] + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PersonMergeTask" + }, + "examples": { + "task-in-progress": { + "$ref": "#/components/examples/task-in-progress" }, - "type": "location" + "task-success": { + "$ref": "#/components/examples/task-success-2" + }, + "task-failed": { + "$ref": "#/components/examples/task-failed" + } } } - ] + }, + "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": { + "securitySchemes": { + "bearerAuth": { + "type": "http", + "scheme": "bearer" + } + }, + "headers": { + "X-Ratelimit-Limit-User": { + "description": "Number of requests allowed per minute for the user", + "schema": { + "type": "integer" + } + }, + "X-Ratelimit-Limit-User-Remaining": { + "description": "Number of requests remaining for the user", + "schema": { + "type": "integer" + } + }, + "X-Ratelimit-Limit-User-Reset": { + "description": "Time in seconds before the limit resets for the user", + "schema": { + "type": "integer" + } + }, + "X-Ratelimit-Limit-Org": { + "description": "Number of requests allowed per month for the account", + "schema": { + "type": "integer" + } + }, + "X-Ratelimit-Limit-Org-Remaining": { + "description": "Number of requests remaining for the account", + "schema": { + "type": "integer" + } + }, + "X-Ratelimit-Limit-Org-Reset": { + "description": "Time in seconds before the limit resets for the account", + "schema": { + "type": "integer" + } + } + }, + "schemas": { + "AuthenticationError": { + "title": "AuthenticationError", + "type": "object", + "properties": { + "code": { + "description": "Error code", + "type": "string", + "const": "authentication" + }, + "message": { + "description": "Error message", + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "additionalProperties": false, + "examples": [ + { + "code": "authentication", + "message": "🚨 Error! Sound the alarm! 🚨" } ] }, - "Pagination": { - "title": "Pagination", + "AuthorizationError": { + "title": "AuthorizationError", "type": "object", "properties": { - "prevUrl": { - "description": "URL for the previous page", - "type": [ - "string", - "null" - ], - "format": "url", - "examples": [ - "https://api.affinity.co/v2/foo?cursor=ICAgICAgYmVmb3JlOjo6Nw" - ] + "code": { + "description": "Error code", + "type": "string", + "const": "authorization" }, - "nextUrl": { - "description": "URL for the next page", - "type": [ - "string", - "null" - ], - "format": "url", - "examples": [ - "https://api.affinity.co/v2/foo?cursor=ICAgICAgIGFmdGVyOjo6NA" - ] + "message": { + "description": "Error message", + "type": "string" } }, + "required": [ + "code", + "message" + ], "additionalProperties": false, "examples": [ { - "prevUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgYmVmb3JlOjo6Nw", - "nextUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgIGFmdGVyOjo6NA" + "code": "authorization", + "message": "🚨 Error! Sound the alarm! 🚨" } ] }, - "CompanyPaged": { - "title": "CompanyPaged", - "description": "CompanyPaged model", + "BadRequestError": { + "title": "BadRequestError", "type": "object", "properties": { - "data": { - "description": "A page of Company results", - "type": "array", - "items": { - "$ref": "#/components/schemas/Company" - }, - "maxItems": 100 + "code": { + "description": "Error code", + "type": "string", + "const": "bad-request" }, - "pagination": { - "$ref": "#/components/schemas/Pagination" + "message": { + "description": "Error message", + "type": "string" } }, "required": [ - "data", - "pagination" + "code", + "message" ], "additionalProperties": false, "examples": [ { - "pagination": { - "prevUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgYmVmb3JlOjo6Nw", - "nextUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgIGFmdGVyOjo6NA" - }, - "data": [ - { - "domain": "acme.co", - "name": "Acme", - "isGlobal": true, - "domains": [ - "acme.co" - ], - "id": 1, - "fields": [ - { - "enrichmentSource": "affinity-data", - "name": "Location", - "id": "affinity-data-location", - "type": "enriched", - "value": { - "data": { - "continent": "North America", - "country": "United States", - "streetAddress": "170 Columbus Ave", - "city": "San Francisco", - "state": "California" - }, - "type": "location" - } - }, - { - "enrichmentSource": "affinity-data", - "name": "Location", - "id": "affinity-data-location", - "type": "enriched", - "value": { - "data": { - "continent": "North America", - "country": "United States", - "streetAddress": "170 Columbus Ave", - "city": "San Francisco", - "state": "California" - }, - "type": "location" - } - } - ] - }, - { - "domain": "acme.co", - "name": "Acme", - "isGlobal": true, - "domains": [ - "acme.co" - ], - "id": 1, - "fields": [ - { - "enrichmentSource": "affinity-data", - "name": "Location", - "id": "affinity-data-location", - "type": "enriched", - "value": { - "data": { - "continent": "North America", - "country": "United States", - "streetAddress": "170 Columbus Ave", - "city": "San Francisco", - "state": "California" - }, - "type": "location" - } - }, - { - "enrichmentSource": "affinity-data", - "name": "Location", - "id": "affinity-data-location", - "type": "enriched", - "value": { - "data": { - "continent": "North America", - "country": "United States", - "streetAddress": "170 Columbus Ave", - "city": "San Francisco", - "state": "California" - }, - "type": "location" - } - } - ] - } - ] + "code": "bad-request", + "message": "🚨 Error! Sound the alarm! 🚨" } ] }, - "AuthorizationErrors": { - "title": "AuthorizationErrors", - "description": "AuthorizationErrors model", + "ConflictError": { + "title": "ConflictError", "type": "object", "properties": { - "errors": { - "description": "AuthorizationError errors", - "type": "array", - "items": { - "$ref": "#/components/schemas/AuthorizationError" - } + "code": { + "description": "Error code", + "type": "string", + "const": "conflict" + }, + "message": { + "description": "Error message", + "type": "string" } }, "required": [ - "errors" + "code", + "message" ], "additionalProperties": false, "examples": [ { - "errors": [ - { - "code": "authorization", - "message": "🚨 Error! Sound the alarm! 🚨" - }, - { - "code": "authorization", - "message": "🚨 Error! Sound the alarm! 🚨" - } - ] + "code": "conflict", + "message": "🚨 Error! Sound the alarm! 🚨" } ] }, - "FieldMetadata": { - "title": "FieldMetadata", + "MethodNotAllowedError": { + "title": "MethodNotAllowedError", "type": "object", "properties": { - "id": { - "description": "The field's unique identifier", - "type": "string", - "examples": [ - "affinity-data-location" - ] - }, - "name": { - "description": "The field's name", - "type": "string", - "examples": [ - "Location" - ] - }, - "type": { - "description": "The field's type", + "code": { + "description": "Error code", "type": "string", - "enum": [ - "enriched", - "global", - "list", - "relationship-intelligence" - ], - "examples": [ - "enriched" - ] - }, - "enrichmentSource": { - "description": "The source of the data in this Field (if it is enriched)", - "type": [ - "string", - "null" - ], - "enum": [ - "affinity-data", - "dealroom", - null - ], - "examples": [ - "affinity-data" - ] + "const": "method-not-allowed" }, - "valueType": { - "description": "The type of the data in this Field", - "type": "string", - "enum": [ - "person", - "person-multi", - "company", - "company-multi", - "filterable-text", - "filterable-text-multi", - "number", - "number-multi", - "datetime", - "location", - "location-multi", - "text", - "ranked-dropdown", - "dropdown", - "dropdown-multi", - "formula-number", - "interaction" - ], - "examples": [ - "location" - ] + "message": { + "description": "Error message", + "type": "string" } }, "required": [ - "enrichmentSource", - "id", - "name", - "type", - "valueType" + "code", + "message" ], "additionalProperties": false, "examples": [ { - "enrichmentSource": "affinity-data", - "valueType": "location", - "name": "Location", - "id": "affinity-data-location", - "type": "enriched" + "code": "method-not-allowed", + "message": "🚨 Error! Sound the alarm! 🚨" } ] }, - "FieldMetadataPaged": { - "title": "FieldMetadataPaged", - "description": "FieldMetadataPaged model", + "NotAcceptableError": { + "title": "NotAcceptableError", "type": "object", "properties": { - "data": { - "description": "A page of FieldMetadata results", - "type": "array", - "items": { - "$ref": "#/components/schemas/FieldMetadata" - }, - "maxItems": 100 + "code": { + "description": "Error code", + "type": "string", + "const": "not-acceptable" }, - "pagination": { - "$ref": "#/components/schemas/Pagination" + "message": { + "description": "Error message", + "type": "string" } }, "required": [ - "data", - "pagination" + "code", + "message" ], - "additionalProperties": false + "additionalProperties": false, + "examples": [ + { + "code": "not-acceptable", + "message": "🚨 Error! Sound the alarm! 🚨" + } + ] }, - "List": { - "title": "List", + "NotFoundError": { + "title": "NotFoundError", "type": "object", "properties": { - "id": { - "description": "The unique identifier for the list", - "type": "integer", - "format": "int64", - "minimum": 1, - "maximum": 9007199254740991, - "examples": [ - 1 - ] - }, - "name": { - "description": "The name of the list", + "code": { + "description": "Error code", "type": "string", - "examples": [ - "All companies" - ] - }, - "creatorId": { - "description": "The ID of the user that created this list", - "type": "integer", - "format": "int64", - "minimum": 1, - "maximum": 9007199254740991, - "examples": [ - 1 - ] - }, - "ownerId": { - "description": "The ID of the user that owns this list", - "type": "integer", - "format": "int64", - "minimum": 1, - "maximum": 9007199254740991, - "examples": [ - 1 - ] + "const": "not-found" }, - "isPublic": { - "description": "Whether or not the list is public", - "type": "boolean", - "examples": [ - false - ] + "message": { + "description": "Error message", + "type": "string" } }, "required": [ - "creatorId", - "id", - "isPublic", - "name", - "ownerId" + "code", + "message" ], "additionalProperties": false, "examples": [ { - "name": "All companies", - "creatorId": 1, - "isPublic": false, - "id": 1, - "ownerId": 1 + "code": "not-found", + "message": "🚨 Error! Sound the alarm! 🚨" } ] }, - "ListPaged": { - "title": "ListPaged", - "description": "ListPaged model", + "NotImplementedError": { + "title": "NotImplementedError", "type": "object", "properties": { - "data": { - "description": "A page of List results", - "type": "array", - "items": { - "$ref": "#/components/schemas/List" - }, - "maxItems": 100 + "code": { + "description": "Error code", + "type": "string", + "const": "not-implemented" }, - "pagination": { - "$ref": "#/components/schemas/Pagination" + "message": { + "description": "Error message", + "type": "string" } }, "required": [ - "data", - "pagination" + "code", + "message" ], "additionalProperties": false, "examples": [ { - "pagination": { - "prevUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgYmVmb3JlOjo6Nw", - "nextUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgIGFmdGVyOjo6NA" - }, - "data": [ - { - "name": "All companies", - "creatorId": 1, - "isPublic": false, - "id": 1, - "ownerId": 1 - }, - { - "name": "All companies", - "creatorId": 1, - "isPublic": false, - "id": 1, - "ownerId": 1 - } - ] + "code": "not-implemented", + "message": "🚨 Error! Sound the alarm! 🚨" } ] }, - "ListEntry": { - "title": "ListEntry", + "RateLimitError": { + "title": "RateLimitError", "type": "object", "properties": { - "id": { - "description": "The list entry's unique identifier", - "type": "integer", - "format": "int64", - "minimum": 1, - "maximum": 9007199254740991, - "examples": [ - 1 - ] - }, - "listId": { - "description": "The ID of the list that this list entry belongs to", - "type": "integer", - "format": "int64", - "minimum": 1, - "maximum": 9007199254740991, - "examples": [ - 1 - ] - }, - "createdAt": { - "description": "The date that the list entry was created", + "code": { + "description": "Error code", "type": "string", - "format": "date-time", - "examples": [ - "2023-01-01T00:00:00Z" - ] + "const": "rate-limit" }, - "creatorId": { - "description": "The ID of the user that created this list entry", - "type": [ - "integer", - "null" - ], - "format": "int64", - "minimum": 1, - "maximum": 9007199254740991, - "examples": [ - 1 - ] + "message": { + "description": "Error message", + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "additionalProperties": false, + "examples": [ + { + "code": "rate-limit", + "message": "🚨 Error! Sound the alarm! 🚨" + } + ] + }, + "ServerError": { + "title": "ServerError", + "type": "object", + "properties": { + "code": { + "description": "Error code", + "type": "string", + "const": "server" }, - "fields": { - "description": "The fields associated with the list entry", - "type": "array", - "items": { - "$ref": "#/components/schemas/Field" - } + "message": { + "description": "Error message", + "type": "string" } }, "required": [ - "createdAt", - "creatorId", - "fields", - "id", - "listId" + "code", + "message" ], "additionalProperties": false, "examples": [ { - "listId": 1, - "createdAt": "2023-01-01T00:00:00Z", - "creatorId": 1, - "id": 1, - "fields": [ - { - "enrichmentSource": "affinity-data", - "name": "Location", - "id": "affinity-data-location", - "type": "enriched", - "value": { - "data": { - "continent": "North America", - "country": "United States", - "streetAddress": "170 Columbus Ave", - "city": "San Francisco", - "state": "California" - }, - "type": "location" - } - }, - { - "enrichmentSource": "affinity-data", - "name": "Location", - "id": "affinity-data-location", - "type": "enriched", - "value": { - "data": { - "continent": "North America", - "country": "United States", - "streetAddress": "170 Columbus Ave", - "city": "San Francisco", - "state": "California" - }, - "type": "location" - } - } - ] + "code": "server", + "message": "🚨 Error! Sound the alarm! 🚨" } ] }, - "ListEntryPaged": { - "title": "ListEntryPaged", - "description": "ListEntryPaged model", + "UnprocessableEntityError": { + "title": "UnprocessableEntityError", "type": "object", "properties": { - "data": { - "description": "A page of ListEntry results", - "type": "array", - "items": { - "$ref": "#/components/schemas/ListEntry" - }, - "maxItems": 100 + "code": { + "description": "Error code", + "type": "string", + "const": "unprocessable-entity" }, - "pagination": { - "$ref": "#/components/schemas/Pagination" + "message": { + "description": "Error message", + "type": "string" } }, "required": [ - "data", - "pagination" + "code", + "message" ], "additionalProperties": false, "examples": [ { - "pagination": { - "prevUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgYmVmb3JlOjo6Nw", - "nextUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgIGFmdGVyOjo6NA" - }, - "data": [ - { - "listId": 1, - "createdAt": "2023-01-01T00:00:00Z", - "creatorId": 1, - "id": 1, - "fields": [ - { - "enrichmentSource": "affinity-data", - "name": "Location", - "id": "affinity-data-location", - "type": "enriched", - "value": { - "data": { - "continent": "North America", - "country": "United States", - "streetAddress": "170 Columbus Ave", - "city": "San Francisco", - "state": "California" - }, - "type": "location" - } - }, - { - "enrichmentSource": "affinity-data", - "name": "Location", - "id": "affinity-data-location", - "type": "enriched", - "value": { - "data": { - "continent": "North America", - "country": "United States", - "streetAddress": "170 Columbus Ave", - "city": "San Francisco", - "state": "California" - }, - "type": "location" - } - } - ] - }, - { - "listId": 1, - "createdAt": "2023-01-01T00:00:00Z", - "creatorId": 1, - "id": 1, - "fields": [ - { - "enrichmentSource": "affinity-data", - "name": "Location", - "id": "affinity-data-location", - "type": "enriched", - "value": { - "data": { - "continent": "North America", - "country": "United States", - "streetAddress": "170 Columbus Ave", - "city": "San Francisco", - "state": "California" - }, - "type": "location" - } - }, - { - "enrichmentSource": "affinity-data", - "name": "Location", - "id": "affinity-data-location", - "type": "enriched", - "value": { - "data": { - "continent": "North America", - "country": "United States", - "streetAddress": "170 Columbus Ave", - "city": "San Francisco", - "state": "California" - }, - "type": "location" - } - } - ] - } - ] + "code": "unprocessable-entity", + "message": "🚨 Error! Sound the alarm! 🚨" } ] }, - "ListWithType": { - "title": "ListWithType", - "description": "ListWithType model", + "UnsupportedMediaTypeError": { + "title": "UnsupportedMediaTypeError", + "type": "object", + "properties": { + "code": { + "description": "Error code", + "type": "string", + "const": "unsupported-media-type" + }, + "message": { + "description": "Error message", + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "additionalProperties": false, + "examples": [ + { + "code": "unsupported-media-type", + "message": "🚨 Error! Sound the alarm! 🚨" + } + ] + }, + "ValidationError": { + "title": "ValidationError", + "type": "object", + "properties": { + "code": { + "description": "Error code", + "type": "string", + "const": "validation" + }, + "message": { + "description": "Error message", + "type": "string" + }, + "param": { + "description": "Param the error refers to", + "type": "string" + } + }, + "required": [ + "code", + "message", + "param" + ], + "additionalProperties": false, + "examples": [ + { + "code": "validation", + "param": "limit", + "message": "🚨 Error! Sound the alarm! 🚨" + } + ] + }, + "Error": { + "title": "Error", + "oneOf": [ + { + "$ref": "#/components/schemas/AuthenticationError" + }, + { + "$ref": "#/components/schemas/AuthorizationError" + }, + { + "$ref": "#/components/schemas/BadRequestError" + }, + { + "$ref": "#/components/schemas/ConflictError" + }, + { + "$ref": "#/components/schemas/MethodNotAllowedError" + }, + { + "$ref": "#/components/schemas/NotAcceptableError" + }, + { + "$ref": "#/components/schemas/NotFoundError" + }, + { + "$ref": "#/components/schemas/NotImplementedError" + }, + { + "$ref": "#/components/schemas/RateLimitError" + }, + { + "$ref": "#/components/schemas/ServerError" + }, + { + "$ref": "#/components/schemas/UnprocessableEntityError" + }, + { + "$ref": "#/components/schemas/UnsupportedMediaTypeError" + }, + { + "$ref": "#/components/schemas/ValidationError" + } + ], + "discriminator": { + "propertyName": "code", + "mapping": { + "authentication": "#/components/schemas/AuthenticationError", + "authorization": "#/components/schemas/AuthorizationError", + "bad-request": "#/components/schemas/BadRequestError", + "conflict": "#/components/schemas/ConflictError", + "method-not-allowed": "#/components/schemas/MethodNotAllowedError", + "not-acceptable": "#/components/schemas/NotAcceptableError", + "not-found": "#/components/schemas/NotFoundError", + "not-implemented": "#/components/schemas/NotImplementedError", + "rate-limit": "#/components/schemas/RateLimitError", + "server": "#/components/schemas/ServerError", + "unprocessable-entity": "#/components/schemas/UnprocessableEntityError", + "unsupported-media-type": "#/components/schemas/UnsupportedMediaTypeError", + "validation": "#/components/schemas/ValidationError" + } + } + }, + "Errors": { + "title": "Errors", + "type": "object", + "properties": { + "errors": { + "description": "Errors", + "type": "array", + "items": { + "$ref": "#/components/schemas/Error" + } + } + }, + "required": [ + "errors" + ], + "additionalProperties": false + }, + "Tenant": { + "title": "Tenant", "type": "object", "properties": { "id": { - "description": "The unique identifier for the list", + "description": "The tenant's unique identifier", "type": "integer", "format": "int64", "minimum": 1, @@ -5142,24 +5312,41 @@ ] }, "name": { - "description": "The name of the list", + "description": "The name of the tenant", "type": "string", "examples": [ - "All companies" + "Contoso Ltd." ] }, - "creatorId": { - "description": "The ID of the user that created this list", - "type": "integer", - "format": "int64", - "minimum": 1, - "maximum": 9007199254740991, + "subdomain": { + "description": "The tenant's subdomain under affinity.co", + "type": "string", + "format": "hostname", "examples": [ - 1 + "contoso" ] - }, - "ownerId": { - "description": "The ID of the user that owns this list", + } + }, + "required": [ + "id", + "name", + "subdomain" + ], + "additionalProperties": false, + "examples": [ + { + "name": "Contoso Ltd.", + "subdomain": "contoso", + "id": 1 + } + ] + }, + "User": { + "title": "User", + "type": "object", + "properties": { + "id": { + "description": "The user's unique identifier", "type": "integer", "format": "int64", "minimum": 1, @@ -5168,178 +5355,182 @@ 1 ] }, - "isPublic": { - "description": "Whether or not the list is public", - "type": "boolean", + "firstName": { + "description": "The user's first name", + "type": "string", "examples": [ - false + "John" ] }, - "type": { - "description": "The entity type for this list", - "type": "string", - "enum": [ - "company", - "opportunity", - "person" + "lastName": { + "description": "The user's last name", + "type": [ + "string", + "null" ], "examples": [ - "company" + "Smith" + ] + }, + "emailAddress": { + "description": "The user's email address", + "type": "string", + "format": "email", + "examples": [ + "john.smith@contoso.com" ] } }, "required": [ - "creatorId", + "emailAddress", + "firstName", "id", - "isPublic", - "name", - "ownerId", - "type" + "lastName" ], - "additionalProperties": false - }, - "ListWithTypePaged": { - "title": "ListWithTypePaged", - "description": "ListWithTypePaged model", - "type": "object", - "properties": { - "data": { - "description": "A page of ListWithType results", - "type": "array", - "items": { - "$ref": "#/components/schemas/ListWithType" - }, - "maxItems": 100 - }, - "pagination": { - "$ref": "#/components/schemas/Pagination" + "additionalProperties": false, + "examples": [ + { + "firstName": "John", + "lastName": "Smith", + "emailAddress": "john.smith@contoso.com", + "id": 1 } - }, - "required": [ - "data", - "pagination" - ], - "additionalProperties": false + ] }, - "CompanyListEntry": { - "title": "CompanyListEntry", + "Grant": { + "title": "Grant", "type": "object", "properties": { - "id": { - "description": "The list entry's unique identifier", - "type": "integer", - "format": "int64", - "minimum": 1, - "maximum": 9007199254740991, - "examples": [ - 1 - ] - }, "type": { - "description": "The entity type for this list entry", + "description": "The type of grant used to authenticate", "type": "string", - "const": "company", + "enum": [ + "api-key", + "access-token" + ], "examples": [ - "company" + "api-key" ] }, - "listId": { - "description": "The ID of the list that this list entry belongs to", - "type": "integer", - "format": "int64", - "minimum": 1, - "maximum": 9007199254740991, + "scopes": { + "description": "The scopes available to the current grant", + "type": "array", + "items": { + "type": "string" + }, "examples": [ - 1 + [ + "api" + ] ] }, "createdAt": { - "description": "The date that the list entry was created", + "description": "When the grant was created", "type": "string", "format": "date-time", "examples": [ "2023-01-01T00:00:00Z" ] - }, - "creatorId": { - "description": "The ID of the user that created this list entry", - "type": [ - "integer", - "null" - ], - "format": "int64", - "minimum": 1, - "maximum": 9007199254740991, - "examples": [ - 1 - ] - }, - "entity": { - "$ref": "#/components/schemas/Company" } }, "required": [ "createdAt", - "creatorId", - "entity", - "id", - "listId", + "scopes", "type" ], - "additionalProperties": false + "additionalProperties": false, + "examples": [ + { + "createdAt": "2023-01-01T00:00:00Z", + "scopes": [ + "api" + ], + "type": "api-key" + } + ] }, - "OpportunityWithFields": { - "title": "OpportunityWithFields", + "WhoAmI": { + "title": "WhoAmI", + "description": "WhoAmI model", "type": "object", "properties": { - "id": { - "description": "The unique identifier for the opportunity", - "type": "integer", - "format": "int64", - "minimum": 1, - "maximum": 9007199254740991, - "examples": [ - 1 - ] - }, - "name": { - "description": "The name of the opportunity", - "type": "string", - "examples": [ - "Acme Upsell $10k" - ] + "tenant": { + "$ref": "#/components/schemas/Tenant" }, - "listId": { - "description": "The ID of the list that the opportunity belongs to", - "type": "integer", - "format": "int64", - "minimum": 1, - "maximum": 9007199254740991, - "examples": [ - 1 - ] + "user": { + "$ref": "#/components/schemas/User" }, - "fields": { - "description": "The fields associated with the opportunity", + "grant": { + "$ref": "#/components/schemas/Grant" + } + }, + "required": [ + "grant", + "tenant", + "user" + ], + "additionalProperties": false, + "examples": [ + { + "grant": { + "createdAt": "2023-01-01T00:00:00Z", + "scopes": [ + "api" + ], + "type": "api-key" + }, + "user": { + "firstName": "John", + "lastName": "Smith", + "emailAddress": "john.smith@contoso.com", + "id": 1 + }, + "tenant": { + "name": "Contoso Ltd.", + "subdomain": "contoso", + "id": 1 + } + } + ] + }, + "NotFoundErrors": { + "title": "NotFoundErrors", + "description": "NotFoundErrors model", + "type": "object", + "properties": { + "errors": { + "description": "NotFoundError errors", "type": "array", "items": { - "$ref": "#/components/schemas/Field" + "$ref": "#/components/schemas/NotFoundError" } } }, "required": [ - "id", - "listId", - "name" + "errors" ], - "additionalProperties": false + "additionalProperties": false, + "examples": [ + { + "errors": [ + { + "code": "not-found", + "message": "🚨 Error! Sound the alarm! 🚨" + }, + { + "code": "not-found", + "message": "🚨 Error! Sound the alarm! 🚨" + } + ] + } + ] }, - "OpportunityListEntry": { - "title": "OpportunityListEntry", + "PersonData": { + "title": "PersonData", "type": "object", "properties": { "id": { - "description": "The list entry's unique identifier", + "description": "The persons's unique identifier", "type": "integer", "format": "int64", "minimum": 1, @@ -5348,79 +5539,14 @@ 1 ] }, - "type": { - "description": "The entity type for this list entry", - "type": "string", - "const": "opportunity", + "firstName": { + "description": "The person's first name", + "type": [ + "string", + "null" + ], "examples": [ - "opportunity" - ] - }, - "listId": { - "description": "The ID of the list that this list entry belongs to", - "type": "integer", - "format": "int64", - "minimum": 1, - "maximum": 9007199254740991, - "examples": [ - 1 - ] - }, - "createdAt": { - "description": "The date that the list entry was created", - "type": "string", - "format": "date-time", - "examples": [ - "2023-01-01T00:00:00Z" - ] - }, - "creatorId": { - "description": "The ID of the user that created this list entry", - "type": [ - "integer", - "null" - ], - "format": "int64", - "minimum": 1, - "maximum": 9007199254740991, - "examples": [ - 1 - ] - }, - "entity": { - "$ref": "#/components/schemas/OpportunityWithFields" - } - }, - "required": [ - "createdAt", - "creatorId", - "entity", - "id", - "listId", - "type" - ], - "additionalProperties": false - }, - "Person": { - "title": "Person", - "description": "Person model", - "type": "object", - "properties": { - "id": { - "description": "The persons's unique identifier", - "type": "integer", - "format": "int64", - "minimum": 1, - "maximum": 9007199254740991, - "examples": [ - 1 - ] - }, - "firstName": { - "description": "The person's first name", - "type": "string", - "examples": [ - "Jane" + "Jane" ] }, "lastName": { @@ -5444,102 +5570,96 @@ "jane.doe@acme.co" ] }, - "emailAddresses": { - "description": "All of the person's email addresses", - "type": "array", - "items": { - "type": "string", - "format": "email" - }, - "examples": [ - [ - "jane.doe@acme.co", - "janedoe@gmail.com" - ] - ] - }, "type": { "description": "The person's type", "type": "string", "enum": [ "internal", - "external" + "external", + "collaborator" ], "examples": [ "internal" ] - }, - "fields": { - "description": "The fields associated with the person", - "type": "array", - "items": { - "$ref": "#/components/schemas/Field" - } } }, "required": [ - "emailAddresses", "firstName", "id", "lastName", "primaryEmailAddress", "type" ], - "additionalProperties": false, - "examples": [ - { - "firstName": "Jane", - "lastName": "Doe", - "emailAddresses": [ - "jane.doe@acme.co", - "janedoe@gmail.com" + "additionalProperties": false + }, + "Attendee": { + "title": "Attendee", + "type": "object", + "properties": { + "emailAddress": { + "description": "The email addresses of the attendee", + "type": [ + "string", + "null" ], - "id": 1, - "type": "internal", - "fields": [ + "format": "email", + "examples": [ + "john.smith@contoso.com" + ] + }, + "person": { + "oneOf": [ { - "enrichmentSource": "affinity-data", - "name": "Location", - "id": "affinity-data-location", - "type": "enriched", - "value": { - "data": { - "continent": "North America", - "country": "United States", - "streetAddress": "170 Columbus Ave", - "city": "San Francisco", - "state": "California" - }, - "type": "location" - } + "$ref": "#/components/schemas/PersonData" }, { - "enrichmentSource": "affinity-data", - "name": "Location", - "id": "affinity-data-location", - "type": "enriched", - "value": { - "data": { - "continent": "North America", - "country": "United States", - "streetAddress": "170 Columbus Ave", - "city": "San Francisco", - "state": "California" - }, - "type": "location" - } + "type": "null" } - ], - "primaryEmailAddress": "jane.doe@acme.co" + ] } - ] + }, + "required": [ + "emailAddress", + "person" + ], + "additionalProperties": false }, - "PersonListEntry": { - "title": "PersonListEntry", + "AttendeesPreview": { + "x-stability-level": "beta", + "title": "interactions.AttendeesPreview", + "type": "object", + "properties": { + "data": { + "description": "A preview of Attendees", + "type": "array", + "items": { + "$ref": "#/components/schemas/Attendee" + }, + "maxItems": 100 + }, + "totalCount": { + "description": "The total count of Attendees", + "type": "integer", + "format": "int64", + "minimum": 0, + "maximum": 9007199254740991, + "examples": [ + 200 + ] + } + }, + "required": [ + "data", + "totalCount" + ], + "additionalProperties": false + }, + "interactions.Call": { + "title": "interactions.Call", "type": "object", "properties": { "id": { - "description": "The list entry's unique identifier", + "description": "The call's unique identifier", "type": "integer", "format": "int64", "minimum": 1, @@ -5548,99 +5668,166 @@ 1 ] }, - "type": { - "description": "The entity type for this list entry", + "loggingType": { + "description": "Indicates how the interaction was added to Affinity: either manually by a user ('manual') or automatically through Affinity's capture process ('automated'). Currently, calls can only be logged as 'manual'.", "type": "string", - "const": "person", + "const": "manual", "examples": [ - "person" + "manual" ] }, - "listId": { - "description": "The ID of the list that this list entry belongs to", - "type": "integer", - "format": "int64", - "minimum": 1, - "maximum": 9007199254740991, + "title": { + "description": "The call's title", + "type": [ + "string", + "null" + ], "examples": [ - 1 + "Example title" + ] + }, + "startTime": { + "description": "The timestamp of when the call starts", + "type": "string", + "format": "date-time", + "examples": [ + "2023-01-01T00:00:00Z" + ] + }, + "endTime": { + "description": "The timestamp of when the call ends", + "type": [ + "string", + "null" + ], + "format": "date-time", + "examples": [ + "2023-01-01T00:00:00Z" + ] + }, + "allDay": { + "description": "Whether the call is all day", + "type": "boolean", + "examples": [ + false + ] + }, + "creator": { + "description": "The person who created the call", + "oneOf": [ + { + "$ref": "#/components/schemas/Attendee" + }, + { + "type": "null" + } ] }, "createdAt": { - "description": "The date that the list entry was created", + "description": "The timestamp of when the call was created", "type": "string", "format": "date-time", "examples": [ "2023-01-01T00:00:00Z" ] }, - "creatorId": { - "description": "The ID of the user that created this list entry", + "updatedAt": { + "description": "The timestamp of when the call was updated", "type": [ - "integer", + "string", "null" ], - "format": "int64", - "minimum": 1, - "maximum": 9007199254740991, + "format": "date-time", "examples": [ - 1 + "2023-01-01T00:00:00Z" ] }, - "entity": { - "$ref": "#/components/schemas/Person" + "attendeesPreview": { + "description": "A preview of the attendees in the call", + "$ref": "#/components/schemas/AttendeesPreview" } }, "required": [ - "createdAt", - "creatorId", - "entity", "id", - "listId", - "type" + "loggingType", + "title", + "startTime", + "endTime", + "allDay", + "creator", + "createdAt", + "updatedAt", + "attendeesPreview" ], "additionalProperties": false }, - "ListEntryWithEntity": { - "title": "ListEntryWithEntity", - "oneOf": [ - { - "$ref": "#/components/schemas/CompanyListEntry" + "Pagination": { + "title": "Pagination", + "type": "object", + "properties": { + "prevUrl": { + "description": "URL for the previous page", + "type": [ + "string", + "null" + ], + "format": "uri", + "examples": [ + "https://api.affinity.co/v2/foo?cursor=ICAgICAgYmVmb3JlOjo6Nw" + ] }, + "nextUrl": { + "description": "URL for the next page", + "type": [ + "string", + "null" + ], + "format": "uri", + "examples": [ + "https://api.affinity.co/v2/foo?cursor=ICAgICAgIGFmdGVyOjo6NA" + ] + } + }, + "examples": [ { - "$ref": "#/components/schemas/OpportunityListEntry" - }, + "prevUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgYmVmb3JlOjo6Nw", + "nextUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgIGFmdGVyOjo6NA" + } + ] + }, + "PaginationWithTotalCount": { + "title": "PaginationWithTotalCount", + "type": "object", + "allOf": [ { - "$ref": "#/components/schemas/PersonListEntry" + "$ref": "#/components/schemas/Pagination" } ], - "discriminator": { - "propertyName": "type", - "mapping": { - "company": "#/components/schemas/CompanyListEntry", - "opportunity": "#/components/schemas/OpportunityListEntry", - "person": "#/components/schemas/PersonListEntry" + "properties": { + "totalCount": { + "description": "The total count of the collection. Only included if requested via the totalCount query string parameter.", + "type": "integer", + "format": "int64", + "minimum": 0, + "maximum": 9007199254740991 } } }, - "ListEntryWithEntityPaged": { - "title": "ListEntryWithEntityPaged", - "description": "ListEntryWithEntityPaged model", + "interactions.CallPaged": { + "title": "interactions.CallPaged", + "description": "CallPaged model", "type": "object", "properties": { "data": { - "description": "A page of ListEntryWithEntity results", - "type": [ - "array", - "null" - ], + "description": "A page of Call results", + "type": "array", "items": { - "$ref": "#/components/schemas/ListEntryWithEntity" + "$ref": "#/components/schemas/interactions.Call" }, "maxItems": 100 }, "pagination": { - "$ref": "#/components/schemas/Pagination" + "$ref": "#/components/schemas/PaginationWithTotalCount" } }, "required": [ @@ -5649,108 +5836,146 @@ ], "additionalProperties": false }, - "FieldPaged": { + "PersonDataPreview": { "x-stability-level": "beta", - "title": "FieldPaged", - "description": "FieldPaged model", + "title": "interactions.PersonDataPreview", "type": "object", "properties": { "data": { - "description": "A page of Field results", + "description": "A preview of persons", "type": "array", "items": { - "$ref": "#/components/schemas/Field" - } + "$ref": "#/components/schemas/PersonData" + }, + "maxItems": 100 }, - "pagination": { - "$ref": "#/components/schemas/Pagination" + "totalCount": { + "description": "The total count of persons", + "type": "integer", + "format": "int64", + "minimum": 0, + "maximum": 9007199254740991, + "examples": [ + 200 + ] } }, "required": [ "data", - "pagination" - ] + "totalCount" + ], + "additionalProperties": false }, - "CompanyReference": { - "x-stability-level": "beta", - "title": "CompanyReference", + "interactions.ChatMessage": { + "title": "interactions.ChatMessage", "type": "object", "properties": { "id": { - "description": "The company's unique identifier", + "description": "The chat message's unique identifier", "type": "integer", "format": "int64", "minimum": 1, - "maximum": 9007199254740991 - } - }, - "required": [ - "id" - ], - "additionalProperties": false - }, - "CompaniesValueUpdate": { - "x-stability-level": "beta", - "title": "CompaniesValueUpdate", - "type": "object", - "properties": { - "type": { - "description": "The type of value", + "maximum": 9007199254740991, + "examples": [ + 1 + ] + }, + "sentAt": { + "description": "The timestamp of when the chat message was sent", "type": "string", - "const": "company-multi" + "format": "date-time", + "examples": [ + "2023-01-01T00:00:00Z" + ] }, - "data": { - "description": "The values for many companies", + "loggingType": { + "description": "Indicates how the interaction was added to Affinity: either manually by a user ('manual') or automatically through Affinity's capture process ('automated'). Currently, chat messages can only be logged as 'manual'.", + "type": "string", + "const": "manual", + "examples": [ + "manual" + ] + }, + "direction": { + "description": "The direction of the chat message", + "type": "string", + "enum": [ + "sent", + "received" + ], + "examples": [ + "sent" + ] + }, + "creator": { + "description": "The creator of the chat message", + "$ref": "#/components/schemas/PersonData" + }, + "createdAt": { + "description": "The timestamp of when the chat message was created", + "type": "string", + "format": "date-time", + "examples": [ + "2022-01-01T00:00:00Z" + ] + }, + "updatedAt": { + "description": "The timestamp of when the chat message was updated", "type": [ - "array", + "string", "null" ], - "items": { - "$ref": "#/components/schemas/CompanyReference" - }, - "maxItems": 100 + "format": "date-time", + "examples": [ + "2023-01-01T00:00:00Z" + ] + }, + "participantsPreview": { + "description": "A preview of the participants who are in the chat message", + "$ref": "#/components/schemas/PersonDataPreview" } }, "required": [ - "data", - "type" + "id", + "sentAt", + "loggingType", + "direction", + "creator", + "createdAt", + "updatedAt", + "participantsPreview" ], "additionalProperties": false }, - "CompanyValueUpdate": { - "x-stability-level": "beta", - "title": "CompanyValueUpdate", + "interactions.ChatMessagePaged": { + "title": "interactions.ChatMessagePaged", + "description": "ChatMessagePaged model", "type": "object", "properties": { - "type": { - "description": "The type of value", - "type": "string", - "const": "company" - }, "data": { - "oneOf": [ - { - "type": "null" - }, - { - "$ref": "#/components/schemas/CompanyReference" - } - ] + "description": "A page of ChatMessage results", + "type": "array", + "items": { + "$ref": "#/components/schemas/interactions.ChatMessage" + }, + "maxItems": 100 + }, + "pagination": { + "$ref": "#/components/schemas/PaginationWithTotalCount" } }, "required": [ "data", - "type" + "pagination" ], "additionalProperties": false }, - "DropdownReference": { - "x-stability-level": "beta", - "title": "DropdownReference", + "CompanyData": { + "title": "CompanyData", "type": "object", "properties": { - "dropdownOptionId": { - "description": "Dropdown item's unique identifier", + "id": { + "description": "The company's unique identifier", "type": "integer", "format": "int64", "minimum": 1, @@ -5758,30 +5983,49 @@ "examples": [ 1 ] + }, + "name": { + "description": "The company's name", + "type": "string", + "examples": [ + "Acme" + ] + }, + "domain": { + "description": "The company's primary domain", + "type": [ + "string", + "null" + ], + "format": "hostname", + "examples": [ + "acme.co" + ] } }, "required": [ - "dropdownOptionId" + "domain", + "id", + "name" ], "additionalProperties": false }, - "DropdownValueUpdate": { - "x-stability-level": "beta", - "title": "DropdownValueUpdate", + "CompanyValue": { + "title": "CompanyValue", "type": "object", "properties": { "type": { "description": "The type of value", "type": "string", - "const": "dropdown" + "const": "company" }, "data": { "oneOf": [ { - "type": "null" + "$ref": "#/components/schemas/CompanyData" }, { - "$ref": "#/components/schemas/DropdownReference" + "type": "null" } ] } @@ -5789,27 +6033,28 @@ "required": [ "data", "type" - ] + ], + "additionalProperties": false }, - "DropdownsValueUpdate": { - "x-stability-level": "beta", - "title": "DropdownsValueUpdate", + "CompaniesValue": { + "title": "CompaniesValue", "type": "object", "properties": { "type": { "description": "The type of value", "type": "string", - "const": "dropdown-multi" + "const": "company-multi" }, "data": { - "description": "The value for many dropdown items", + "description": "The values for many companies", "type": [ "array", "null" ], "items": { - "$ref": "#/components/schemas/DropdownReference" - } + "$ref": "#/components/schemas/CompanyData" + }, + "maxItems": 100 } }, "required": [ @@ -5818,44 +6063,74 @@ ], "additionalProperties": false }, - "PersonReference": { - "x-stability-level": "beta", - "title": "PersonReference", + "DateValue": { + "title": "DateValue", "type": "object", "properties": { - "id": { - "description": "The persons's unique identifier", - "type": "integer", - "format": "int64", - "minimum": 1, - "maximum": 9007199254740991, - "examples": [ - 1 - ] - } - }, - "required": [ - "id" - ], - "additionalProperties": false + "type": { + "description": "The type of value", + "type": "string", + "const": "datetime" + }, + "data": { + "description": "The value for a date", + "type": [ + "string", + "null" + ], + "format": "date-time" + } + }, + "required": [ + "data", + "type" + ], + "additionalProperties": false }, - "PersonValueUpdate": { - "x-stability-level": "beta", - "title": "PersonValueUpdate", + "Dropdown": { + "title": "Dropdown", + "type": "object", + "properties": { + "dropdownOptionId": { + "description": "Dropdown item's unique identifier", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 1 + ] + }, + "text": { + "description": "Dropdown item text", + "type": "string", + "examples": [ + "first" + ] + } + }, + "required": [ + "dropdownOptionId", + "text" + ], + "additionalProperties": false + }, + "DropdownValue": { + "title": "DropdownValue", "type": "object", "properties": { "type": { "description": "The type of value", "type": "string", - "const": "person" + "const": "dropdown" }, "data": { "oneOf": [ { - "type": "null" + "$ref": "#/components/schemas/Dropdown" }, { - "$ref": "#/components/schemas/PersonReference" + "type": "null" } ] } @@ -5866,26 +6141,24 @@ ], "additionalProperties": false }, - "PersonsValueUpdate": { - "x-stability-level": "beta", - "title": "PersonsValueUpdate", + "DropdownsValue": { + "title": "DropdownsValue", "type": "object", "properties": { "type": { "description": "The type of value", "type": "string", - "const": "person-multi" + "const": "dropdown-multi" }, "data": { - "description": "The values for many persons", + "description": "The value for many dropdown items", "type": [ "array", "null" ], "items": { - "$ref": "#/components/schemas/PersonReference" - }, - "maxItems": 100 + "$ref": "#/components/schemas/Dropdown" + } } }, "required": [ @@ -5894,44 +6167,140 @@ ], "additionalProperties": false }, - "RankedDropdownReference": { - "x-stability-level": "beta", - "title": "RankedDropdownReference", + "FloatValue": { + "title": "FloatValue", "type": "object", "properties": { - "dropdownOptionId": { - "description": "Ranked Dropdown item's unique identifier", - "type": "integer", - "format": "int64", - "minimum": 1, - "maximum": 9007199254740991, + "type": { + "description": "The type of value", + "type": "string", + "const": "number" + }, + "data": { + "description": "The value for a number", + "type": [ + "number", + "null" + ] + } + }, + "required": [ + "data", + "type" + ], + "additionalProperties": false + }, + "FloatsValue": { + "title": "FloatsValue", + "type": "object", + "properties": { + "type": { + "description": "The type of value", + "type": "string", + "const": "number-multi" + }, + "data": { + "description": "The value for many numbers", + "type": [ + "array", + "null" + ], + "items": { + "type": "number" + } + } + }, + "required": [ + "data", + "type" + ], + "additionalProperties": false + }, + "TextValue": { + "title": "TextValue", + "type": "object", + "properties": { + "type": { + "description": "The type of value", + "type": "string", + "enum": [ + "filterable-text", + "text" + ], "examples": [ - 1 + "filterable-text" + ] + }, + "data": { + "description": "The value for a string", + "type": [ + "string", + "null" ] } }, "required": [ - "dropdownOptionId" + "data", + "type" ], "additionalProperties": false }, - "RankedDropdownValueUpdate": { - "x-stability-level": "beta", - "title": "RankedDropdownValueUpdate", + "TextsValue": { + "title": "TextsValue", "type": "object", "properties": { "type": { "description": "The type of value", "type": "string", - "const": "ranked-dropdown" + "const": "filterable-text-multi" + }, + "data": { + "description": "The value for many strings", + "type": [ + "array", + "null" + ], + "items": { + "type": "string" + } + } + }, + "required": [ + "data", + "type" + ], + "additionalProperties": false + }, + "FormulaNumber": { + "title": "FormulaNumber", + "type": "object", + "properties": { + "calculatedValue": { + "description": "Calculated value", + "type": [ + "number", + "null" + ] + } + }, + "additionalProperties": false + }, + "FormulaValue": { + "title": "FormulaValue", + "type": "object", + "properties": { + "type": { + "description": "The type of value", + "type": "string", + "const": "formula-number" }, "data": { "oneOf": [ { - "type": "null" + "$ref": "#/components/schemas/FormulaNumber" }, { - "$ref": "#/components/schemas/RankedDropdownReference" + "type": "null" } ] } @@ -5939,300 +6308,154 @@ "required": [ "data", "type" - ] + ], + "additionalProperties": false }, - "FieldValueUpdate": { - "x-stability-level": "beta", - "title": "FieldValueUpdate", - "oneOf": [ - { - "$ref": "#/components/schemas/CompaniesValueUpdate" + "ChatMessage": { + "title": "ChatMessage", + "type": "object", + "properties": { + "type": { + "description": "The type of interaction", + "type": "string", + "const": "chat-message", + "examples": [ + "chat-message" + ] }, - { - "$ref": "#/components/schemas/CompanyValueUpdate" + "id": { + "description": "The chat message's unique identifier", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 1 + ] }, - { - "$ref": "#/components/schemas/DateValue" + "direction": { + "description": "The direction of the chat message", + "type": "string", + "enum": [ + "received", + "sent" + ], + "examples": [ + "sent" + ] }, - { - "$ref": "#/components/schemas/DropdownValueUpdate" + "sentAt": { + "description": "The time the chat message was sent", + "type": "string", + "format": "date-time", + "examples": [ + "2023-01-01T00:00:00Z" + ] }, - { - "$ref": "#/components/schemas/DropdownsValueUpdate" - }, - { - "$ref": "#/components/schemas/FloatValue" - }, - { - "$ref": "#/components/schemas/FloatsValue" - }, - { - "$ref": "#/components/schemas/LocationValue" - }, - { - "$ref": "#/components/schemas/LocationsValue" - }, - { - "$ref": "#/components/schemas/PersonValueUpdate" - }, - { - "$ref": "#/components/schemas/PersonsValueUpdate" - }, - { - "$ref": "#/components/schemas/RankedDropdownValueUpdate" - }, - { - "$ref": "#/components/schemas/TextValue" - }, - { - "$ref": "#/components/schemas/TextsValue" - } - ], - "discriminator": { - "propertyName": "type", - "mapping": { - "company-multi": "#/components/schemas/CompaniesValueUpdate", - "company": "#/components/schemas/CompanyValueUpdate", - "datetime": "#/components/schemas/DateValue", - "dropdown": "#/components/schemas/DropdownValueUpdate", - "dropdown-multi": "#/components/schemas/DropdownsValueUpdate", - "number": "#/components/schemas/FloatValue", - "number-multi": "#/components/schemas/FloatsValue", - "location": "#/components/schemas/LocationValue", - "location-multi": "#/components/schemas/LocationsValue", - "person": "#/components/schemas/PersonValueUpdate", - "person-multi": "#/components/schemas/PersonsValueUpdate", - "ranked-dropdown": "#/components/schemas/RankedDropdownValueUpdate", - "filterable-text": "#/components/schemas/TextValue", - "filterable-text-multi": "#/components/schemas/TextsValue", - "text": "#/components/schemas/TextValue" - } - }, - "examples": [ - { - "type": "location", - "data": { - "continent": "North America", - "country": "United States", - "streetAddress": "170 Columbus Ave", - "city": "San Francisco", - "state": "California" - } - } - ] - }, - "ListEntryBatchOperationUpdateFields": { - "x-stability-level": "beta", - "title": "ListEntryBatchOperationUpdateFields", - "description": "Update multiple field values.", - "type": "object", - "properties": { - "operation": { - "type": "string", - "const": "update-fields" + "manualCreator": { + "$ref": "#/components/schemas/PersonData" }, - "updates": { + "participants": { + "description": "The participants of the chat", "type": "array", - "maxItems": 100, "items": { - "type": "object", - "properties": { - "id": { - "description": "The field's unique identifier.", - "type": "string", - "format": "string", - "examples": [ - "field-105" - ] - }, - "value": { - "$ref": "#/components/schemas/FieldValueUpdate" - } - }, - "required": [ - "id" - ] + "$ref": "#/components/schemas/PersonData" } } }, "required": [ - "operation", - "updates" - ] - }, - "ListEntryBatchOperationRequest": { - "x-stability-level": "beta", - "title": "ListEntryBatchOperationRequest", - "type": "object", - "oneOf": [ - { - "$ref": "#/components/schemas/ListEntryBatchOperationUpdateFields" - }, - { - "type": "null" - } - ], - "discriminator": { - "propertyName": "operation", - "mapping": { - "update-fields": "#/components/schemas/ListEntryBatchOperationUpdateFields" - } - } - }, - "ListEntryBatchOperations": { - "x-stability-level": "beta", - "title": "ListEntryBatchOperations", - "type": "string", - "enum": [ - "update-fields" - ] - }, - "ListEntryBatchOperationResponse": { - "x-stability-level": "beta", - "title": "ListEntryBatchOperationResponse", - "type": "object", - "properties": { - "operation": { - "$ref": "#/components/schemas/ListEntryBatchOperations" - } - } - }, - "FieldUpdate": { - "x-stability-level": "beta", - "title": "FieldUpdate", - "type": "object", - "properties": { - "value": { - "$ref": "#/components/schemas/FieldValueUpdate" - } - }, - "examples": [ - { - "value": { - "data": { - "continent": "North America", - "country": "United States", - "streetAddress": "170 Columbus Ave", - "city": "San Francisco", - "state": "California" - }, - "type": "location" - } - } + "direction", + "id", + "manualCreator", + "participants", + "sentAt", + "type" ], "additionalProperties": false }, - "SavedView": { - "title": "SavedView", - "description": "SavedView model", + "Email": { + "title": "Email", "type": "object", "properties": { + "type": { + "description": "The type of interaction", + "type": "string", + "const": "email", + "examples": [ + "email" + ] + }, "id": { - "description": "The saved view's unique identifier", + "description": "The email's unique identifier", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "examples": [ - 28 - ] - }, - "name": { - "description": "The saved view's name", - "type": "string", - "examples": [ - "my interesting companies" + 1 ] }, - "type": { - "description": "The type for this saved view", - "type": "string", - "enum": [ - "sheet", - "board", - "dashboard" + "subject": { + "description": "The subject of the email", + "type": [ + "string", + "null" ], "examples": [ - "sheet" + "Acme Upsell $10k" ] }, - "createdAt": { - "description": "The date that the saved view was created", + "sentAt": { + "description": "The time the email was sent", "type": "string", "format": "date-time", "examples": [ "2023-01-01T00:00:00Z" ] + }, + "from": { + "$ref": "#/components/schemas/Attendee" + }, + "to": { + "description": "The recipients of the email", + "type": "array", + "items": { + "$ref": "#/components/schemas/Attendee" + } + }, + "cc": { + "description": "The cc recipients of the email", + "type": "array", + "items": { + "$ref": "#/components/schemas/Attendee" + } } }, "required": [ - "createdAt", + "cc", + "from", "id", - "name", + "sentAt", + "subject", + "to", "type" ], - "additionalProperties": false, - "examples": [ - { - "createdAt": "2023-01-01T00:00:00Z", - "name": "my interesting companies", - "id": 28, - "type": "sheet" - } - ] + "additionalProperties": false }, - "SavedViewPaged": { - "title": "SavedViewPaged", - "description": "SavedViewPaged model", + "Meeting": { + "title": "Meeting", "type": "object", "properties": { - "data": { - "description": "A page of SavedView results", - "type": "array", - "items": { - "$ref": "#/components/schemas/SavedView" - }, - "maxItems": 100 + "type": { + "description": "The type of interaction", + "type": "string", + "const": "meeting", + "examples": [ + "meeting" + ] }, - "pagination": { - "$ref": "#/components/schemas/Pagination" - } - }, - "required": [ - "data", - "pagination" - ], - "additionalProperties": false, - "examples": [ - { - "pagination": { - "prevUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgYmVmb3JlOjo6Nw", - "nextUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgIGFmdGVyOjo6NA" - }, - "data": [ - { - "createdAt": "2023-01-01T00:00:00Z", - "name": "my interesting companies", - "id": 28, - "type": "sheet" - }, - { - "createdAt": "2023-01-01T00:00:00Z", - "name": "my interesting companies", - "id": 28, - "type": "sheet" - } - ] - } - ] - }, - "Opportunity": { - "title": "Opportunity", - "description": "Opportunity model", - "type": "object", - "properties": { "id": { - "description": "The unique identifier for the opportunity", + "description": "The meeting's unique identifier", "type": "integer", "format": "int64", "minimum": 1, @@ -6241,15 +6464,75 @@ 1 ] }, - "name": { - "description": "The name of the opportunity", - "type": "string", + "title": { + "description": "The meeting's title", + "type": [ + "string", + "null" + ], "examples": [ "Acme Upsell $10k" ] }, - "listId": { - "description": "The ID of the list that the opportunity belongs to", + "allDay": { + "description": "Whether the meeting is an all-day event", + "type": "boolean", + "examples": [ + false + ] + }, + "startTime": { + "description": "The meeting start time", + "type": "string", + "format": "date-time", + "examples": [ + "2023-02-03T04:00:00Z" + ] + }, + "endTime": { + "description": "The meeting end time", + "type": [ + "string", + "null" + ], + "format": "date-time", + "examples": [ + "2023-02-03T05:00:00Z" + ] + }, + "attendees": { + "description": "People attending the meeting", + "type": "array", + "items": { + "$ref": "#/components/schemas/Attendee" + } + } + }, + "required": [ + "allDay", + "attendees", + "endTime", + "id", + "startTime", + "title", + "type" + ], + "additionalProperties": false + }, + "PhoneCall": { + "title": "PhoneCall", + "type": "object", + "properties": { + "type": { + "description": "The type of interaction", + "type": "string", + "const": "call", + "examples": [ + "call" + ] + }, + "id": { + "description": "The phone call's unique identifier", "type": "integer", "format": "int64", "minimum": 1, @@ -6257,405 +6540,4779 @@ "examples": [ 1 ] + }, + "startTime": { + "description": "The call start time", + "type": "string", + "format": "date-time", + "examples": [ + "2023-02-03T04:00:00Z" + ] + }, + "attendees": { + "description": "People attending the call", + "type": "array", + "items": { + "$ref": "#/components/schemas/Attendee" + } } }, "required": [ + "attendees", "id", - "listId", - "name" + "startTime", + "type" ], - "additionalProperties": false, - "examples": [ + "additionalProperties": false + }, + "Interaction": { + "title": "Interaction", + "oneOf": [ { - "listId": 1, - "name": "Acme Upsell $10k", - "id": 1 + "$ref": "#/components/schemas/ChatMessage" + }, + { + "$ref": "#/components/schemas/Email" + }, + { + "$ref": "#/components/schemas/Meeting" + }, + { + "$ref": "#/components/schemas/PhoneCall" } - ] + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "chat-message": "#/components/schemas/ChatMessage", + "email": "#/components/schemas/Email", + "meeting": "#/components/schemas/Meeting", + "call": "#/components/schemas/PhoneCall" + } + } }, - "OpportunityPaged": { - "title": "OpportunityPaged", - "description": "OpportunityPaged model", + "InteractionValue": { + "title": "InteractionValue", "type": "object", "properties": { - "data": { - "description": "A page of Opportunity results", - "type": "array", - "items": { - "$ref": "#/components/schemas/Opportunity" - }, - "maxItems": 100 + "type": { + "description": "The type of value", + "type": "string", + "const": "interaction" }, - "pagination": { - "$ref": "#/components/schemas/Pagination" - } - }, - "required": [ - "data", - "pagination" - ], - "additionalProperties": false, - "examples": [ - { - "pagination": { - "prevUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgYmVmb3JlOjo6Nw", - "nextUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgIGFmdGVyOjo6NA" - }, - "data": [ + "data": { + "oneOf": [ { - "listId": 1, - "name": "Acme Upsell $10k", - "id": 1 + "$ref": "#/components/schemas/Interaction" }, { - "listId": 1, - "name": "Acme Upsell $10k", - "id": 1 + "type": "null" } ] } - ] - }, - "PersonPaged": { - "title": "PersonPaged", - "description": "PersonPaged model", - "type": "object", - "properties": { - "data": { - "description": "A page of Person results", - "type": "array", - "items": { - "$ref": "#/components/schemas/Person" - }, - "maxItems": 100 - }, - "pagination": { - "$ref": "#/components/schemas/Pagination" - } }, "required": [ "data", - "pagination" + "type" ], - "additionalProperties": false, - "examples": [ - { - "pagination": { - "prevUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgYmVmb3JlOjo6Nw", - "nextUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgIGFmdGVyOjo6NA" - }, - "data": [ - { - "firstName": "Jane", - "lastName": "Doe", - "emailAddresses": [ - "jane.doe@acme.co", - "janedoe@gmail.com" - ], - "id": 1, - "type": "internal", - "fields": [ - { - "enrichmentSource": "affinity-data", - "name": "Location", - "id": "affinity-data-location", - "type": "enriched", - "value": { - "data": { - "continent": "North America", - "country": "United States", - "streetAddress": "170 Columbus Ave", - "city": "San Francisco", - "state": "California" - }, - "type": "location" - } - }, - { - "enrichmentSource": "affinity-data", - "name": "Location", - "id": "affinity-data-location", - "type": "enriched", - "value": { - "data": { - "continent": "North America", - "country": "United States", - "streetAddress": "170 Columbus Ave", - "city": "San Francisco", - "state": "California" - }, - "type": "location" - } - } - ], - "primaryEmailAddress": "jane.doe@acme.co" - }, - { - "firstName": "Jane", - "lastName": "Doe", - "emailAddresses": [ - "jane.doe@acme.co", - "janedoe@gmail.com" - ], - "id": 1, - "type": "internal", - "fields": [ - { - "enrichmentSource": "affinity-data", - "name": "Location", - "id": "affinity-data-location", - "type": "enriched", - "value": { - "data": { - "continent": "North America", - "country": "United States", - "streetAddress": "170 Columbus Ave", - "city": "San Francisco", - "state": "California" - }, - "type": "location" - } - }, - { - "enrichmentSource": "affinity-data", - "name": "Location", - "id": "affinity-data-location", - "type": "enriched", - "value": { - "data": { - "continent": "North America", - "country": "United States", - "streetAddress": "170 Columbus Ave", - "city": "San Francisco", - "state": "California" - }, - "type": "location" - } - } - ], - "primaryEmailAddress": "jane.doe@acme.co" - } + "additionalProperties": false + }, + "Location": { + "title": "Location", + "type": "object", + "properties": { + "streetAddress": { + "description": "Street address", + "type": [ + "string", + "null" + ], + "examples": [ + "1 Main Street" ] - } - ] - } - }, - "responses": { - "400": { - "description": "Bad Request", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "oneOf": [ - { - "$ref": "#/components/schemas/BadRequestError" - }, - { - "$ref": "#/components/schemas/ValidationError" - } - ], - "discriminator": { - "propertyName": "code", - "mapping": { - "bad-request": "#/components/schemas/BadRequestError", - "validation": "#/components/schemas/ValidationError" - } - } - } - } - }, - "required": [ - "errors" - ], - "additionalProperties": false - } - } - }, - "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" + "city": { + "description": "City", + "type": [ + "string", + "null" + ], + "examples": [ + "San Francisco" + ] }, - "X-Ratelimit-Limit-Org": { - "$ref": "#/components/headers/X-Ratelimit-Limit-Org" + "state": { + "description": "State", + "type": [ + "string", + "null" + ], + "examples": [ + "California" + ] }, - "X-Ratelimit-Limit-Org-Remaining": { - "$ref": "#/components/headers/X-Ratelimit-Limit-Org-Remaining" + "country": { + "description": "Country", + "type": [ + "string", + "null" + ], + "examples": [ + "United States" + ] }, - "X-Ratelimit-Limit-Org-Reset": { - "$ref": "#/components/headers/X-Ratelimit-Limit-Org-Reset" + "continent": { + "description": "Continent", + "type": [ + "string", + "null" + ], + "examples": [ + "North America" + ] } - } + }, + "required": [ + "city", + "continent", + "country", + "state", + "streetAddress" + ], + "additionalProperties": false, + "examples": [ + { + "continent": "North America", + "country": "United States", + "streetAddress": "1 Main Street", + "city": "San Francisco", + "state": "California" + } + ] }, - "403": { - "description": "Forbidden", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AuthorizationErrors" - } + "LocationValue": { + "title": "LocationValue", + "type": "object", + "properties": { + "type": { + "description": "The type of value", + "type": "string", + "const": "location" + }, + "data": { + "oneOf": [ + { + "$ref": "#/components/schemas/Location" + }, + { + "type": "null" + } + ] } }, - "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" + "required": [ + "data", + "type" + ], + "additionalProperties": false + }, + "LocationsValue": { + "title": "LocationsValue", + "type": "object", + "properties": { + "type": { + "description": "The type of value", + "type": "string", + "const": "location-multi" }, - "X-Ratelimit-Limit-Org-Reset": { - "$ref": "#/components/headers/X-Ratelimit-Limit-Org-Reset" + "data": { + "description": "The values for many locations", + "type": [ + "array", + "null" + ], + "items": { + "$ref": "#/components/schemas/Location" + } } - } + }, + "required": [ + "data", + "type" + ], + "additionalProperties": false }, - "404": { - "description": "Not Found", - "content": { - "application/json": { - "schema": { + "PersonValue": { + "title": "PersonValue", + "type": "object", + "properties": { + "type": { + "description": "The type of value", + "type": "string", + "const": "person" + }, + "data": { + "oneOf": [ + { + "$ref": "#/components/schemas/PersonData" + }, + { + "type": "null" + } + ] + } + }, + "required": [ + "data", + "type" + ], + "additionalProperties": false + }, + "PersonsValue": { + "title": "PersonsValue", + "type": "object", + "properties": { + "type": { + "description": "The type of value", + "type": "string", + "const": "person-multi" + }, + "data": { + "description": "The values for many persons", + "type": [ + "array", + "null" + ], + "items": { + "$ref": "#/components/schemas/PersonData" + }, + "maxItems": 100 + } + }, + "required": [ + "data", + "type" + ], + "additionalProperties": false + }, + "RankedDropdown": { + "title": "RankedDropdown", + "type": "object", + "properties": { + "dropdownOptionId": { + "description": "Dropdown item's unique identifier", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 1 + ] + }, + "text": { + "description": "Dropdown item text", + "type": "string", + "examples": [ + "first" + ] + }, + "rank": { + "description": "Dropdown item rank", + "type": "integer", + "format": "int64", + "minimum": 0, + "maximum": 9007199254740991, + "examples": [ + 0 + ] + }, + "color": { + "description": "Dropdown item color", + "type": [ + "string", + "null" + ], + "examples": [ + "white" + ] + } + }, + "required": [ + "color", + "dropdownOptionId", + "rank", + "text" + ], + "additionalProperties": false + }, + "RankedDropdownValue": { + "title": "RankedDropdownValue", + "type": "object", + "properties": { + "type": { + "description": "The type of value", + "type": "string", + "const": "ranked-dropdown" + }, + "data": { + "oneOf": [ + { + "$ref": "#/components/schemas/RankedDropdown" + }, + { + "type": "null" + } + ] + } + }, + "required": [ + "data", + "type" + ], + "additionalProperties": false + }, + "FieldValue": { + "title": "FieldValue", + "oneOf": [ + { + "$ref": "#/components/schemas/CompaniesValue" + }, + { + "$ref": "#/components/schemas/CompanyValue" + }, + { + "$ref": "#/components/schemas/DateValue" + }, + { + "$ref": "#/components/schemas/DropdownsValue" + }, + { + "$ref": "#/components/schemas/DropdownValue" + }, + { + "$ref": "#/components/schemas/FloatsValue" + }, + { + "$ref": "#/components/schemas/FloatValue" + }, + { + "$ref": "#/components/schemas/FormulaValue" + }, + { + "$ref": "#/components/schemas/InteractionValue" + }, + { + "$ref": "#/components/schemas/LocationsValue" + }, + { + "$ref": "#/components/schemas/LocationValue" + }, + { + "$ref": "#/components/schemas/PersonsValue" + }, + { + "$ref": "#/components/schemas/PersonValue" + }, + { + "$ref": "#/components/schemas/RankedDropdownValue" + }, + { + "$ref": "#/components/schemas/TextsValue" + }, + { + "$ref": "#/components/schemas/TextValue" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "company": "#/components/schemas/CompanyValue", + "company-multi": "#/components/schemas/CompaniesValue", + "datetime": "#/components/schemas/DateValue", + "dropdown": "#/components/schemas/DropdownValue", + "dropdown-multi": "#/components/schemas/DropdownsValue", + "number": "#/components/schemas/FloatValue", + "number-multi": "#/components/schemas/FloatsValue", + "filterable-text": "#/components/schemas/TextValue", + "filterable-text-multi": "#/components/schemas/TextsValue", + "formula-number": "#/components/schemas/FormulaValue", + "interaction": "#/components/schemas/InteractionValue", + "location": "#/components/schemas/LocationValue", + "location-multi": "#/components/schemas/LocationsValue", + "person": "#/components/schemas/PersonValue", + "person-multi": "#/components/schemas/PersonsValue", + "ranked-dropdown": "#/components/schemas/RankedDropdownValue", + "text": "#/components/schemas/TextValue" + } + }, + "examples": [ + { + "data": { + "continent": "North America", + "country": "United States", + "streetAddress": "1 Main Street", + "city": "San Francisco", + "state": "California" + }, + "type": "location" + } + ] + }, + "Field": { + "title": "Field", + "type": "object", + "properties": { + "id": { + "description": "The field's unique identifier", + "type": "string", + "examples": [ + "affinity-data-location", + "field-1234" + ] + }, + "name": { + "description": "The field's name", + "type": "string", + "examples": [ + "Location" + ] + }, + "type": { + "description": "The field's type", + "type": "string", + "enum": [ + "enriched", + "global", + "list", + "relationship-intelligence" + ], + "examples": [ + "enriched" + ] + }, + "enrichmentSource": { + "description": "The source of the data in this Field (if it is enriched)", + "type": [ + "string", + "null" + ], + "enum": [ + "affinity-data", + "dealroom", + "eventbrite", + "mailchimp", + null + ], + "examples": [ + "affinity-data" + ] + }, + "value": { + "$ref": "#/components/schemas/FieldValue" + } + }, + "required": [ + "enrichmentSource", + "id", + "name", + "type", + "value" + ], + "additionalProperties": false, + "examples": [ + { + "enrichmentSource": "affinity-data", + "name": "Location", + "id": "affinity-data-location", + "type": "enriched", + "value": { + "data": { + "continent": "North America", + "country": "United States", + "streetAddress": "1 Main Street", + "city": "San Francisco", + "state": "California" + }, + "type": "location" + } + } + ] + }, + "Company": { + "title": "Company", + "description": "Company model", + "type": "object", + "properties": { + "id": { + "description": "The company's unique identifier", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 1 + ] + }, + "name": { + "description": "The company's name", + "type": "string", + "examples": [ + "Acme" + ] + }, + "domain": { + "description": "The company's primary domain", + "type": [ + "string", + "null" + ], + "format": "hostname", + "examples": [ + "acme.co" + ] + }, + "domains": { + "description": "All of the company's domains", + "type": "array", + "items": { + "type": "string", + "format": "hostname" + }, + "examples": [ + [ + "acme.co" + ] + ] + }, + "isGlobal": { + "description": "Whether or not the company is tenant specific", + "type": "boolean", + "examples": [ + true + ] + }, + "fields": { + "description": "The fields associated with the company", + "type": "array", + "items": { + "$ref": "#/components/schemas/Field" + } + } + }, + "required": [ + "domain", + "domains", + "id", + "isGlobal", + "name" + ], + "additionalProperties": false, + "examples": [ + { + "domain": "acme.co", + "name": "Acme", + "isGlobal": true, + "domains": [ + "acme.co" + ], + "id": 1, + "fields": [ + { + "enrichmentSource": "affinity-data", + "name": "Location", + "id": "affinity-data-location", + "type": "enriched", + "value": { + "data": { + "continent": "North America", + "country": "United States", + "streetAddress": "1 Main Street", + "city": "San Francisco", + "state": "California" + }, + "type": "location" + } + }, + { + "enrichmentSource": "affinity-data", + "name": "Description", + "id": "affinity-data-description", + "type": "enriched", + "value": { + "data": "A leading provider of innovative solutions", + "type": "text" + } + } + ] + } + ] + }, + "CompanyPaged": { + "title": "CompanyPaged", + "description": "CompanyPaged model", + "type": "object", + "properties": { + "data": { + "description": "A page of Company results", + "type": "array", + "items": { + "$ref": "#/components/schemas/Company" + }, + "maxItems": 100 + }, + "pagination": { + "$ref": "#/components/schemas/Pagination" + } + }, + "required": [ + "data", + "pagination" + ], + "additionalProperties": false, + "examples": [ + { + "pagination": { + "prevUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgYmVmb3JlOjo6Nw", + "nextUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgIGFmdGVyOjo6NA" + }, + "data": [ + { + "domain": "acme.co", + "name": "Acme", + "isGlobal": true, + "domains": [ + "acme.co" + ], + "id": 1, + "fields": [ + { + "enrichmentSource": "affinity-data", + "name": "Location", + "id": "affinity-data-location", + "type": "enriched", + "value": { + "data": { + "continent": "North America", + "country": "United States", + "streetAddress": "1 Main Street", + "city": "San Francisco", + "state": "California" + }, + "type": "location" + } + }, + { + "enrichmentSource": "affinity-data", + "name": "Description", + "id": "affinity-data-description", + "type": "enriched", + "value": { + "data": "A leading provider of innovative solutions", + "type": "text" + } + } + ] + }, + { + "domain": "umbrella.co", + "name": "Umbrella Corporation", + "isGlobal": true, + "domains": [ + "umbrella.co" + ], + "id": 2, + "fields": [ + { + "enrichmentSource": "affinity-data", + "name": "Location", + "id": "affinity-data-location", + "type": "enriched", + "value": { + "data": { + "continent": "North America", + "country": "United States", + "streetAddress": "200 Corporate Blvd", + "city": "Raccoon City", + "state": "Ohio" + }, + "type": "location" + } + }, + { + "enrichmentSource": "affinity-data", + "name": "Description", + "id": "affinity-data-description", + "type": "enriched", + "value": { + "data": "Pharmaceutical and biotechnology company", + "type": "text" + } + } + ] + } + ] + } + ] + }, + "AuthorizationErrors": { + "title": "AuthorizationErrors", + "description": "AuthorizationErrors model", + "type": "object", + "properties": { + "errors": { + "description": "AuthorizationError errors", + "type": "array", + "items": { + "$ref": "#/components/schemas/AuthorizationError" + } + } + }, + "required": [ + "errors" + ], + "additionalProperties": false, + "examples": [ + { + "errors": [ + { + "code": "authorization", + "message": "🚨 Error! Sound the alarm! 🚨" + }, + { + "code": "authorization", + "message": "🚨 Error! Sound the alarm! 🚨" + } + ] + } + ] + }, + "FieldMetadata": { + "title": "FieldMetadata", + "type": "object", + "properties": { + "id": { + "description": "The field's unique identifier", + "type": "string", + "examples": [ + "affinity-data-location", + "field-1234" + ] + }, + "name": { + "description": "The field's name", + "type": "string", + "examples": [ + "Location" + ] + }, + "type": { + "description": "The field's type", + "type": "string", + "enum": [ + "enriched", + "global", + "list", + "relationship-intelligence" + ], + "examples": [ + "enriched" + ] + }, + "enrichmentSource": { + "description": "The source of the data in this Field (if it is enriched)", + "type": [ + "string", + "null" + ], + "enum": [ + "affinity-data", + "dealroom", + "eventbrite", + "mailchimp", + null + ], + "examples": [ + "affinity-data" + ] + }, + "valueType": { + "description": "The type of the data in this Field", + "type": "string", + "enum": [ + "person", + "person-multi", + "company", + "company-multi", + "filterable-text", + "filterable-text-multi", + "number", + "number-multi", + "datetime", + "location", + "location-multi", + "text", + "ranked-dropdown", + "dropdown", + "dropdown-multi", + "formula-number", + "interaction" + ], + "examples": [ + "location" + ] + } + }, + "required": [ + "enrichmentSource", + "id", + "name", + "type", + "valueType" + ], + "additionalProperties": false, + "examples": [ + { + "enrichmentSource": "affinity-data", + "valueType": "location", + "name": "Location", + "id": "affinity-data-location", + "type": "enriched" + } + ] + }, + "FieldMetadataPaged": { + "title": "FieldMetadataPaged", + "description": "FieldMetadataPaged model", + "type": "object", + "properties": { + "data": { + "description": "A page of FieldMetadata results", + "type": "array", + "items": { + "$ref": "#/components/schemas/FieldMetadata" + }, + "maxItems": 100 + }, + "pagination": { + "$ref": "#/components/schemas/Pagination" + } + }, + "required": [ + "data", + "pagination" + ], + "additionalProperties": false + }, + "ListEntry": { + "title": "ListEntry", + "type": "object", + "properties": { + "id": { + "description": "The list entry's unique identifier", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 1 + ] + }, + "listId": { + "description": "The ID of the list that this list entry belongs to", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 1 + ] + }, + "createdAt": { + "description": "The date that the list entry was created", + "type": "string", + "format": "date-time", + "examples": [ + "2023-01-01T00:00:00Z" + ] + }, + "creatorId": { + "description": "The ID of the user that created this list entry", + "type": [ + "integer", + "null" + ], + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 1 + ] + }, + "fields": { + "description": "The fields associated with the list entry", + "type": "array", + "items": { + "$ref": "#/components/schemas/Field" + } + } + }, + "required": [ + "createdAt", + "creatorId", + "fields", + "id", + "listId" + ], + "additionalProperties": false, + "examples": [ + { + "listId": 1, + "createdAt": "2023-01-01T00:00:00Z", + "creatorId": 1, + "id": 1, + "fields": [ + { + "enrichmentSource": "affinity-data", + "name": "Location", + "id": "affinity-data-location", + "type": "enriched", + "value": { + "data": { + "continent": "North America", + "country": "United States", + "streetAddress": "1 Main Street", + "city": "San Francisco", + "state": "California" + }, + "type": "location" + } + }, + { + "enrichmentSource": "affinity-data", + "name": "Location", + "id": "affinity-data-location", + "type": "enriched", + "value": { + "data": { + "continent": "North America", + "country": "United States", + "streetAddress": "1 Main Street", + "city": "San Francisco", + "state": "California" + }, + "type": "location" + } + } + ] + } + ] + }, + "ListEntryPaged": { + "title": "ListEntryPaged", + "description": "ListEntryPaged model", + "type": "object", + "properties": { + "data": { + "description": "A page of ListEntry results", + "type": "array", + "items": { + "$ref": "#/components/schemas/ListEntry" + }, + "maxItems": 100 + }, + "pagination": { + "$ref": "#/components/schemas/Pagination" + } + }, + "required": [ + "data", + "pagination" + ], + "additionalProperties": false, + "examples": [ + { + "pagination": { + "prevUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgYmVmb3JlOjo6Nw", + "nextUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgIGFmdGVyOjo6NA" + }, + "data": [ + { + "listId": 1, + "createdAt": "2023-01-01T00:00:00Z", + "creatorId": 1, + "id": 1, + "fields": [ + { + "enrichmentSource": "affinity-data", + "name": "Location", + "id": "affinity-data-location", + "type": "enriched", + "value": { + "data": { + "continent": "North America", + "country": "United States", + "streetAddress": "1 Main Street", + "city": "San Francisco", + "state": "California" + }, + "type": "location" + } + }, + { + "enrichmentSource": "affinity-data", + "name": "Location", + "id": "affinity-data-location", + "type": "enriched", + "value": { + "data": { + "continent": "North America", + "country": "United States", + "streetAddress": "1 Main Street", + "city": "San Francisco", + "state": "California" + }, + "type": "location" + } + } + ] + }, + { + "listId": 1, + "createdAt": "2023-01-01T00:00:00Z", + "creatorId": 1, + "id": 1, + "fields": [ + { + "enrichmentSource": "affinity-data", + "name": "Location", + "id": "affinity-data-location", + "type": "enriched", + "value": { + "data": { + "continent": "North America", + "country": "United States", + "streetAddress": "1 Main Street", + "city": "San Francisco", + "state": "California" + }, + "type": "location" + } + }, + { + "enrichmentSource": "affinity-data", + "name": "Location", + "id": "affinity-data-location", + "type": "enriched", + "value": { + "data": { + "continent": "North America", + "country": "United States", + "streetAddress": "1 Main Street", + "city": "San Francisco", + "state": "California" + }, + "type": "location" + } + } + ] + } + ] + } + ] + }, + "List": { + "title": "List", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for the list", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 1 + ] + }, + "name": { + "description": "The name of the list", + "type": "string", + "examples": [ + "All companies" + ] + }, + "creatorId": { + "description": "The ID of the user that created this list", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 1 + ] + }, + "ownerId": { + "description": "The ID of the user that owns this list", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 1 + ] + }, + "isPublic": { + "description": "Whether or not the list is public", + "type": "boolean", + "examples": [ + false + ] + } + }, + "required": [ + "creatorId", + "id", + "isPublic", + "name", + "ownerId" + ], + "additionalProperties": false, + "examples": [ + { + "name": "All companies", + "creatorId": 1, + "isPublic": false, + "id": 1, + "ownerId": 1 + } + ] + }, + "ListPaged": { + "title": "ListPaged", + "description": "ListPaged model", + "type": "object", + "properties": { + "data": { + "description": "A page of List results", + "type": "array", + "items": { + "$ref": "#/components/schemas/List" + }, + "maxItems": 100 + }, + "pagination": { + "$ref": "#/components/schemas/Pagination" + } + }, + "required": [ + "data", + "pagination" + ], + "additionalProperties": false, + "examples": [ + { + "pagination": { + "prevUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgYmVmb3JlOjo6Nw", + "nextUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgIGFmdGVyOjo6NA" + }, + "data": [ + { + "name": "All companies", + "creatorId": 1, + "isPublic": false, + "id": 1, + "ownerId": 1 + }, + { + "name": "All companies", + "creatorId": 1, + "isPublic": false, + "id": 1, + "ownerId": 1 + } + ] + } + ] + }, + "notes.Content": { + "x-stability-level": "beta", + "title": "notes.Content", + "description": "A note content", + "type": "object", + "properties": { + "html": { + "description": "The HTML content of the note", + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "html" + ] + }, + "notes.PersonMention": { + "x-stability-level": "beta", + "title": "notes.PersonMention", + "description": "A person mentioned in a note.", + "type": "object", + "properties": { + "id": { + "description": "The id of the mention", + "type": "integer", + "format": "int32", + "minimum": 1, + "maximum": 2147483647 + }, + "type": { + "description": "The type of mention", + "type": "string", + "const": "person" + }, + "person": { + "$ref": "#/components/schemas/PersonData" + } + }, + "required": [ + "id", + "type", + "person" + ] + }, + "notes.Mention": { + "x-stability-level": "beta", + "title": "notes.Mention", + "description": "A mention in a note.", + "oneOf": [ + { + "$ref": "#/components/schemas/notes.PersonMention" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "person": "#/components/schemas/notes.PersonMention" + } + } + }, + "notes.BaseNote": { + "x-stability-level": "beta", + "title": "notes.BaseNote", + "description": "An abstract base class for notes", + "type": "object", + "properties": { + "id": { + "description": "The id of the note", + "type": "integer", + "format": "int32", + "minimum": 1, + "maximum": 2147483647 + }, + "content": { + "$ref": "#/components/schemas/notes.Content" + }, + "creator": { + "$ref": "#/components/schemas/PersonData" + }, + "mentions": { + "description": "The mentions in the note", + "type": "array", + "items": { + "$ref": "#/components/schemas/notes.Mention" + }, + "maxItems": 100 + }, + "createdAt": { + "description": "The date and time the note was created", + "type": "string", + "format": "date-time" + }, + "updatedAt": { + "description": "The date and time the note was last updated", + "type": [ + "string", + "null" + ], + "format": "date-time" + } + }, + "required": [ + "id", + "content", + "creator", + "mentions", + "createdAt", + "updatedAt" + ] + }, + "notes.PermissionSettings": { + "x-stability-level": "beta", + "title": "notes.PermissionSettings", + "description": "The permission settings of a note", + "type": "object", + "properties": { + "sharingType": { + "description": "The sharing type of the note", + "type": "string", + "enum": [ + "private", + "public", + "custom" + ] + }, + "owner": { + "$ref": "#/components/schemas/PersonData" + } + }, + "required": [ + "sharingType", + "owner" + ] + }, + "Opportunity": { + "title": "Opportunity", + "description": "Opportunity model", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for the opportunity", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 1 + ] + }, + "name": { + "description": "The name of the opportunity", + "type": "string", + "examples": [ + "Acme Upsell $10k" + ] + }, + "listId": { + "description": "The ID of the list that the opportunity belongs to", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 1 + ] + } + }, + "required": [ + "id", + "listId", + "name" + ], + "additionalProperties": false, + "examples": [ + { + "listId": 1, + "name": "Acme Upsell $10k", + "id": 1 + } + ] + }, + "notes.OpportunitiesPreview": { + "x-stability-level": "beta", + "title": "notes.OpportunitiesPreview", + "description": "A preview for attached Opportunities on a Note", + "type": "object", + "properties": { + "data": { + "description": "Preview of attached Opportunities for a Note", + "type": "array", + "items": { + "$ref": "#/components/schemas/Opportunity" + }, + "maxItems": 100 + }, + "totalCount": { + "description": "The total count of the collection parameter.", + "type": "integer", + "format": "int64", + "minimum": 0, + "maximum": 9007199254740991 + } + } + }, + "notes.PersonsPreview": { + "x-stability-level": "beta", + "title": "notes.PersonsPreview", + "description": "A preview for attached Persons on a Note", + "type": "object", + "properties": { + "data": { + "description": "Preview of attached Persons for a Note", + "type": "array", + "items": { + "$ref": "#/components/schemas/PersonData" + }, + "maxItems": 100 + }, + "totalCount": { + "description": "The total count of the collection parameter.", + "type": "integer", + "format": "int64", + "minimum": 0, + "maximum": 9007199254740991 + } + } + }, + "notes.CompaniesPreview": { + "x-stability-level": "beta", + "title": "notes.CompaniesPreview", + "description": "A preview for attached Companies on a Note", + "type": "object", + "properties": { + "data": { + "description": "Preview of attached Companies for a Note", + "type": "array", + "items": { + "$ref": "#/components/schemas/CompanyData" + }, + "maxItems": 100 + }, + "totalCount": { + "description": "The total count of the collection parameter.", + "type": "integer", + "format": "int64", + "minimum": 0, + "maximum": 9007199254740991 + } + } + }, + "notes.BaseRootNote": { + "x-stability-level": "beta", + "title": "notes.BaseRootNote", + "description": "A root note", + "allOf": [ + { + "$ref": "#/components/schemas/notes.BaseNote" + } + ], + "properties": { + "repliesCount": { + "description": "The number of replies to this note. This is only included if the `repliesCount` parameter is passed in the `includes` in the request and the note is not a reply itself.", + "type": "integer", + "format": "int32", + "minimum": 0, + "maximum": 2147483647 + }, + "permissions": { + "$ref": "#/components/schemas/notes.PermissionSettings" + }, + "opportunitiesPreview": { + "$ref": "#/components/schemas/notes.OpportunitiesPreview" + }, + "personsPreview": { + "$ref": "#/components/schemas/notes.PersonsPreview" + }, + "companiesPreview": { + "$ref": "#/components/schemas/notes.CompaniesPreview" + } + } + }, + "notes.EntitiesNote": { + "x-stability-level": "beta", + "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" + ] + }, + "notes.MeetingInteraction": { + "x-stability-level": "beta", + "title": "notes.MeetingInteraction", + "description": "This is a Meeting (Event) object attached to a note", + "type": "object", + "properties": { + "id": { + "description": "The id of the Meeting (Event)", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991 + }, + "type": { + "description": "The type of the Interaction", + "type": "string", + "const": "meeting" + } + }, + "required": [ + "id", + "type" + ] + }, + "notes.CallInteraction": { + "x-stability-level": "beta", + "title": "notes.CallInteraction", + "description": "This is a Call (Event) object attached to a note", + "type": "object", + "properties": { + "id": { + "description": "The id of the Call (Event)", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991 + }, + "type": { + "description": "The type of the Interaction", + "type": "string", + "const": "call" + } + }, + "required": [ + "id", + "type" + ] + }, + "notes.ChatMessageInteraction": { + "x-stability-level": "beta", + "title": "notes.ChatMessageInteraction", + "description": "A ChatMessage object attached to a note", + "type": "object", + "properties": { + "id": { + "description": "The id of the ChatMessage", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991 + }, + "type": { + "description": "The type of the Interaction", + "type": "string", + "const": "chat-message" + } + }, + "required": [ + "id", + "type" + ] + }, + "notes.EmailInteraction": { + "x-stability-level": "beta", + "title": "notes.EmailInteraction", + "description": "This is an Email object attached to a note", + "type": "object", + "properties": { + "id": { + "description": "The id of the Email", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991 + }, + "type": { + "description": "The type of the Interaction", + "type": "string", + "const": "email" + } + }, + "required": [ + "id", + "type" + ] + }, + "notes.Interaction": { + "x-stability-level": "beta", + "title": "notes.NoteInteraction", + "description": "An interaction attached to a Note. It can be a Meeting, a Call or an ChatMessage.", + "oneOf": [ + { + "$ref": "#/components/schemas/notes.MeetingInteraction" + }, + { + "$ref": "#/components/schemas/notes.CallInteraction" + }, + { + "$ref": "#/components/schemas/notes.ChatMessageInteraction" + }, + { + "$ref": "#/components/schemas/notes.EmailInteraction" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "meeting": "#/components/schemas/notes.MeetingInteraction", + "call": "#/components/schemas/notes.CallInteraction", + "chat-message": "#/components/schemas/notes.ChatMessageInteraction", + "email": "#/components/schemas/notes.EmailInteraction" + } + } + }, + "notes.InteractionNote": { + "x-stability-level": "beta", + "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" + ] + }, + "notes.AiNotetakerRootNote": { + "x-stability-level": "beta", + "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": { + "description": "The meeting this AI Notetaker was invited to.", + "$ref": "#/components/schemas/notes.MeetingInteraction" + } + }, + "required": [ + "type" + ] + }, + "notes.BaseReply": { + "x-stability-level": "beta", + "title": "notes.BaseReply", + "description": "An abstract base class for note replies, either of a UserNoteReply or AiNotetakerNoteReply", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/notes.BaseNote" + } + ], + "properties": { + "parent": { + "type": "object", + "properties": { + "id": { + "description": "The id of the parent note", + "type": "integer", + "format": "int32", + "minimum": 1, + "maximum": 2147483647 + } + }, + "required": [ + "id" + ] + } + }, + "required": [ + "parent" + ] + }, + "notes.UserReplyNote": { + "x-stability-level": "beta", + "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" + ] + }, + "notes.AiNotetakerReplyNote": { + "x-stability-level": "beta", + "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": { + "description": "The meeting this AI Notetaker was invited to.", + "$ref": "#/components/schemas/notes.MeetingInteraction" + } + }, + "required": [ + "type" + ] + }, + "notes.Note": { + "x-stability-level": "beta", + "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": "#/components/schemas/notes.EntitiesNote", + "interaction": "#/components/schemas/notes.InteractionNote", + "ai-notetaker": "#/components/schemas/notes.AiNotetakerRootNote", + "user-reply": "#/components/schemas/notes.UserReplyNote", + "ai-notetaker-reply": "#/components/schemas/notes.AiNotetakerReplyNote" + } + } + }, + "notes.NotesPaged": { + "x-stability-level": "beta", + "title": "notes.NotesPaged", + "description": "NotesPaged model", + "type": "object", + "properties": { + "data": { + "description": "A page of Note objects", + "type": "array", + "items": { + "$ref": "#/components/schemas/notes.Note" + }, + "maxItems": 100 + }, + "pagination": { + "$ref": "#/components/schemas/PaginationWithTotalCount" + } + }, + "required": [ + "data", + "pagination" + ] + }, + "CompanyMergeState": { + "title": "CompanyMergeState", + "description": "Entity representing the state of an individual company merge", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for the merge", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 12345 + ] + }, + "status": { + "description": "Current status of the merge", + "type": "string", + "enum": [ + "in-progress", + "success", + "failed" + ], + "examples": [ + "success" + ] + }, + "taskId": { + "description": "Identifier for the task this merge belongs to", + "type": "string", + "format": "uuid", + "examples": [ + "789e0123-e45b-67c8-d901-234567890123" + ] + }, + "startedAt": { + "description": "Timestamp when the merge started", + "type": "string", + "format": "date-time", + "examples": [ + "2025-06-03T10:30:00Z" + ] + }, + "primaryCompanyId": { + "description": "ID of the primary company that other profiles were merged into", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 12345 + ] + }, + "duplicateCompanyId": { + "description": "ID of the duplicate company that was merged into the primary company", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 67890 + ] + }, + "completedAt": { + "description": "Timestamp when the merge completed (success or failure)", + "type": [ + "string", + "null" + ], + "format": "date-time", + "examples": [ + "2025-06-03T10:32:15Z", + null + ] + }, + "errorMessage": { + "description": "Error message if the merge failed", + "type": [ + "string", + "null" + ], + "examples": [ + "Primary company not found", + null + ] + } + }, + "required": [ + "id", + "status", + "taskId", + "startedAt", + "primaryCompanyId", + "duplicateCompanyId", + "completedAt", + "errorMessage" + ], + "additionalProperties": false + }, + "CompanyMergeStatePaged": { + "title": "CompanyMergeStatePaged", + "description": "Paginated list of company merge states", + "type": "object", + "properties": { + "data": { + "description": "Array of company merge states", + "type": "array", + "maxItems": 100, + "items": { + "$ref": "#/components/schemas/CompanyMergeState" + } + }, + "pagination": { + "$ref": "#/components/schemas/Pagination" + } + }, + "required": [ + "data", + "pagination" + ], + "additionalProperties": false + }, + "CompanyMergeRequest": { + "title": "CompanyMergeRequest", + "description": "Request body for initiating a company merge", + "type": "object", + "properties": { + "primaryCompanyId": { + "description": "The ID of the company profile that will be kept after the merge. All data from the duplicate company will be merged into this company.", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 12345 + ] + }, + "duplicateCompanyId": { + "description": "The ID of the company profile that will be merged and then deleted. All data from this company will be transferred to the primary company.", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 67890 + ] + } + }, + "required": [ + "primaryCompanyId", + "duplicateCompanyId" + ], + "additionalProperties": false + }, + "CompanyMergeResponse": { + "title": "CompanyMergeResponse", + "description": "Response body for initiating a company merge", + "type": "object", + "properties": { + "taskUrl": { + "description": "URL to check the status of the merge task", + "type": "string", + "format": "uri", + "examples": [ + "https://api.affinit.com/tasks/company-merges/123e4567-e89b-12d3-a456-426614174000" + ] + } + }, + "required": [ + "taskUrl" + ], + "additionalProperties": false + }, + "interactions.Email": { + "title": "interactions.Email", + "type": "object", + "properties": { + "id": { + "description": "The email's unique identifier", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 1 + ] + }, + "sentAt": { + "description": "The timestamp of when the email was sent", + "type": "string", + "format": "date-time", + "examples": [ + "2023-01-01T00:00:00Z" + ] + }, + "loggingType": { + "description": "Indicates how the interaction was added to Affinity: either manually by a user ('manual') or automatically through Affinity's capture process ('automated'). Currently, emails can only be logged as 'automated'.", + "type": "string", + "const": "automated", + "examples": [ + "automated" + ] + }, + "direction": { + "description": "The direction of the email: 'sent' if the email was sent by an internal user and 'received' if the email was sent to an internal user.", + "type": "string", + "enum": [ + "sent", + "received" + ], + "examples": [ + "received" + ] + }, + "subject": { + "description": "The email's subject", + "type": [ + "string", + "null" + ], + "examples": [ + "Example subject" + ] + }, + "createdAt": { + "description": "The timestamp of when the email was created", + "type": "string", + "format": "date-time", + "examples": [ + "2023-01-01T00:00:00Z" + ] + }, + "updatedAt": { + "description": "The timestamp of when the email was updated", + "type": [ + "string", + "null" + ], + "format": "date-time", + "examples": [ + "2023-01-01T00:00:00Z" + ] + }, + "from": { + "description": "The participant who sent the email", + "$ref": "#/components/schemas/Attendee" + }, + "toParticipantsPreview": { + "description": "A preview of the participants in the 'To' field of the email", + "$ref": "#/components/schemas/AttendeesPreview" + }, + "ccParticipantsPreview": { + "description": "A preview of the participants who are cc'ed in the email", + "$ref": "#/components/schemas/AttendeesPreview" + } + }, + "required": [ + "id", + "sentAt", + "loggingType", + "direction", + "subject", + "createdAt", + "updatedAt", + "from", + "toParticipantsPreview", + "ccParticipantsPreview" + ], + "additionalProperties": false + }, + "interactions.EmailPaged": { + "title": "interactions.EmailPaged", + "description": "EmailPaged model", + "type": "object", + "properties": { + "data": { + "description": "A page of Email results", + "type": "array", + "items": { + "$ref": "#/components/schemas/interactions.Email" + }, + "maxItems": 100 + }, + "pagination": { + "$ref": "#/components/schemas/PaginationWithTotalCount" + } + }, + "required": [ + "data", + "pagination" + ], + "additionalProperties": false + }, + "ListWithType": { + "title": "ListWithType", + "description": "ListWithType model", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for the list", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 1 + ] + }, + "name": { + "description": "The name of the list", + "type": "string", + "examples": [ + "All companies" + ] + }, + "creatorId": { + "description": "The ID of the user that created this list", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 1 + ] + }, + "ownerId": { + "description": "The ID of the user that owns this list", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 1 + ] + }, + "isPublic": { + "description": "Whether or not the list is public", + "type": "boolean", + "examples": [ + false + ] + }, + "type": { + "description": "The entity type for this list", + "type": "string", + "enum": [ + "company", + "opportunity", + "person" + ], + "examples": [ + "company" + ] + } + }, + "required": [ + "creatorId", + "id", + "isPublic", + "name", + "ownerId", + "type" + ], + "additionalProperties": false + }, + "ListWithTypePaged": { + "title": "ListWithTypePaged", + "description": "ListWithTypePaged model", + "type": "object", + "properties": { + "data": { + "description": "A page of ListWithType results", + "type": "array", + "items": { + "$ref": "#/components/schemas/ListWithType" + }, + "maxItems": 100 + }, + "pagination": { + "$ref": "#/components/schemas/Pagination" + } + }, + "required": [ + "data", + "pagination" + ], + "additionalProperties": false + }, + "CompanyListEntry": { + "title": "CompanyListEntry", + "type": "object", + "properties": { + "id": { + "description": "The list entry's unique identifier", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 1 + ] + }, + "type": { + "description": "The entity type for this list entry", + "type": "string", + "const": "company", + "examples": [ + "company" + ] + }, + "listId": { + "description": "The ID of the list that this list entry belongs to", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 1 + ] + }, + "createdAt": { + "description": "The date that the list entry was created", + "type": "string", + "format": "date-time", + "examples": [ + "2023-01-01T00:00:00Z" + ] + }, + "creatorId": { + "description": "The ID of the user that created this list entry", + "type": [ + "integer", + "null" + ], + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 1 + ] + }, + "entity": { + "$ref": "#/components/schemas/Company" + } + }, + "required": [ + "createdAt", + "creatorId", + "entity", + "id", + "listId", + "type" + ], + "additionalProperties": false + }, + "OpportunityWithFields": { + "title": "OpportunityWithFields", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for the opportunity", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 1 + ] + }, + "name": { + "description": "The name of the opportunity", + "type": "string", + "examples": [ + "Acme Upsell $10k" + ] + }, + "listId": { + "description": "The ID of the list that the opportunity belongs to", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 1 + ] + }, + "fields": { + "description": "The fields associated with the opportunity", + "type": "array", + "items": { + "$ref": "#/components/schemas/Field" + } + } + }, + "required": [ + "id", + "listId", + "name" + ], + "additionalProperties": false + }, + "OpportunityListEntry": { + "title": "OpportunityListEntry", + "type": "object", + "properties": { + "id": { + "description": "The list entry's unique identifier", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 1 + ] + }, + "type": { + "description": "The entity type for this list entry", + "type": "string", + "const": "opportunity", + "examples": [ + "opportunity" + ] + }, + "listId": { + "description": "The ID of the list that this list entry belongs to", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 1 + ] + }, + "createdAt": { + "description": "The date that the list entry was created", + "type": "string", + "format": "date-time", + "examples": [ + "2023-01-01T00:00:00Z" + ] + }, + "creatorId": { + "description": "The ID of the user that created this list entry", + "type": [ + "integer", + "null" + ], + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 1 + ] + }, + "entity": { + "$ref": "#/components/schemas/OpportunityWithFields" + } + }, + "required": [ + "createdAt", + "creatorId", + "entity", + "id", + "listId", + "type" + ], + "additionalProperties": false + }, + "Person": { + "title": "Person", + "description": "Person model", + "type": "object", + "properties": { + "id": { + "description": "The persons's unique identifier", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 1 + ] + }, + "firstName": { + "description": "The person's first name", + "type": "string", + "examples": [ + "Jane" + ] + }, + "lastName": { + "description": "The person's last name", + "type": [ + "string", + "null" + ], + "examples": [ + "Doe" + ] + }, + "primaryEmailAddress": { + "description": "The person's primary email address", + "type": [ + "string", + "null" + ], + "format": "email", + "examples": [ + "jane.doe@acme.co" + ] + }, + "emailAddresses": { + "description": "All of the person's email addresses", + "type": "array", + "items": { + "type": "string", + "format": "email" + }, + "examples": [ + [ + "jane.doe@acme.co", + "janedoe@gmail.com" + ] + ] + }, + "type": { + "description": "The person's type", + "type": "string", + "enum": [ + "internal", + "external" + ], + "examples": [ + "internal" + ] + }, + "fields": { + "description": "The fields associated with the person", + "type": "array", + "items": { + "$ref": "#/components/schemas/Field" + } + } + }, + "required": [ + "emailAddresses", + "firstName", + "id", + "lastName", + "primaryEmailAddress", + "type" + ], + "additionalProperties": false, + "examples": [ + { + "firstName": "Jane", + "lastName": "Doe", + "emailAddresses": [ + "jane.doe@acme.co", + "janedoe@gmail.com" + ], + "id": 1, + "type": "internal", + "fields": [ + { + "enrichmentSource": "affinity-data", + "name": "Location", + "id": "affinity-data-location", + "type": "enriched", + "value": { + "data": { + "continent": "North America", + "country": "United States", + "streetAddress": "1 Main Street", + "city": "San Francisco", + "state": "California" + }, + "type": "location" + } + }, + { + "enrichmentSource": "affinity-data", + "name": "Location", + "id": "affinity-data-location", + "type": "enriched", + "value": { + "data": { + "continent": "North America", + "country": "United States", + "streetAddress": "1 Main Street", + "city": "San Francisco", + "state": "California" + }, + "type": "location" + } + } + ], + "primaryEmailAddress": "jane.doe@acme.co" + } + ] + }, + "PersonListEntry": { + "title": "PersonListEntry", + "type": "object", + "properties": { + "id": { + "description": "The list entry's unique identifier", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 1 + ] + }, + "type": { + "description": "The entity type for this list entry", + "type": "string", + "const": "person", + "examples": [ + "person" + ] + }, + "listId": { + "description": "The ID of the list that this list entry belongs to", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 1 + ] + }, + "createdAt": { + "description": "The date that the list entry was created", + "type": "string", + "format": "date-time", + "examples": [ + "2023-01-01T00:00:00Z" + ] + }, + "creatorId": { + "description": "The ID of the user that created this list entry", + "type": [ + "integer", + "null" + ], + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 1 + ] + }, + "entity": { + "$ref": "#/components/schemas/Person" + } + }, + "required": [ + "createdAt", + "creatorId", + "entity", + "id", + "listId", + "type" + ], + "additionalProperties": false + }, + "ListEntryWithEntity": { + "title": "ListEntryWithEntity", + "oneOf": [ + { + "$ref": "#/components/schemas/CompanyListEntry" + }, + { + "$ref": "#/components/schemas/OpportunityListEntry" + }, + { + "$ref": "#/components/schemas/PersonListEntry" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "company": "#/components/schemas/CompanyListEntry", + "opportunity": "#/components/schemas/OpportunityListEntry", + "person": "#/components/schemas/PersonListEntry" + } + } + }, + "ListEntryWithEntityPaged": { + "title": "ListEntryWithEntityPaged", + "description": "ListEntryWithEntityPaged model", + "type": "object", + "properties": { + "data": { + "description": "A page of ListEntryWithEntity results", + "type": [ + "array", + "null" + ], + "items": { + "$ref": "#/components/schemas/ListEntryWithEntity" + }, + "maxItems": 100 + }, + "pagination": { + "$ref": "#/components/schemas/Pagination" + } + }, + "required": [ + "data", + "pagination" + ], + "additionalProperties": false + }, + "FieldPaged": { + "title": "FieldPaged", + "description": "FieldPaged model", + "type": "object", + "properties": { + "data": { + "description": "A page of Field results", + "type": "array", + "items": { + "$ref": "#/components/schemas/Field" + }, + "maxItems": 100 + }, + "pagination": { + "$ref": "#/components/schemas/Pagination" + } + }, + "required": [ + "data", + "pagination" + ] + }, + "CompanyReference": { + "title": "CompanyReference", + "type": "object", + "properties": { + "id": { + "description": "The company's unique identifier", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991 + } + }, + "required": [ + "id" + ], + "additionalProperties": false + }, + "CompaniesValueUpdate": { + "title": "CompaniesValueUpdate", + "type": "object", + "properties": { + "type": { + "description": "The type of value", + "type": "string", + "const": "company-multi" + }, + "data": { + "description": "The values for many companies", + "type": [ + "array", + "null" + ], + "items": { + "$ref": "#/components/schemas/CompanyReference" + }, + "maxItems": 100 + } + }, + "required": [ + "data", + "type" + ], + "additionalProperties": false + }, + "CompanyValueUpdate": { + "title": "CompanyValueUpdate", + "type": "object", + "properties": { + "type": { + "description": "The type of value", + "type": "string", + "const": "company" + }, + "data": { + "oneOf": [ + { + "type": "null" + }, + { + "$ref": "#/components/schemas/CompanyReference" + } + ] + } + }, + "required": [ + "data", + "type" + ], + "additionalProperties": false + }, + "DropdownReference": { + "title": "DropdownReference", + "type": "object", + "properties": { + "dropdownOptionId": { + "description": "Dropdown item's unique identifier", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 1 + ] + } + }, + "required": [ + "dropdownOptionId" + ], + "additionalProperties": false + }, + "DropdownValueUpdate": { + "title": "DropdownValueUpdate", + "type": "object", + "properties": { + "type": { + "description": "The type of value", + "type": "string", + "const": "dropdown" + }, + "data": { + "oneOf": [ + { + "type": "null" + }, + { + "$ref": "#/components/schemas/DropdownReference" + } + ] + } + }, + "required": [ + "data", + "type" + ] + }, + "DropdownsValueUpdate": { + "title": "DropdownsValueUpdate", + "type": "object", + "properties": { + "type": { + "description": "The type of value", + "type": "string", + "const": "dropdown-multi" + }, + "data": { + "description": "The value for many dropdown items", + "type": [ + "array", + "null" + ], + "items": { + "$ref": "#/components/schemas/DropdownReference" + } + } + }, + "required": [ + "data", + "type" + ], + "additionalProperties": false + }, + "PersonReference": { + "title": "PersonReference", + "type": "object", + "properties": { + "id": { + "description": "The persons's unique identifier", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 1 + ] + } + }, + "required": [ + "id" + ], + "additionalProperties": false + }, + "PersonValueUpdate": { + "title": "PersonValueUpdate", + "type": "object", + "properties": { + "type": { + "description": "The type of value", + "type": "string", + "const": "person" + }, + "data": { + "oneOf": [ + { + "type": "null" + }, + { + "$ref": "#/components/schemas/PersonReference" + } + ] + } + }, + "required": [ + "data", + "type" + ], + "additionalProperties": false + }, + "PersonsValueUpdate": { + "title": "PersonsValueUpdate", + "type": "object", + "properties": { + "type": { + "description": "The type of value", + "type": "string", + "const": "person-multi" + }, + "data": { + "description": "The values for many persons", + "type": [ + "array", + "null" + ], + "items": { + "$ref": "#/components/schemas/PersonReference" + }, + "maxItems": 100 + } + }, + "required": [ + "data", + "type" + ], + "additionalProperties": false + }, + "RankedDropdownReference": { + "title": "RankedDropdownReference", + "type": "object", + "properties": { + "dropdownOptionId": { + "description": "Ranked Dropdown item's unique identifier", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 1 + ] + } + }, + "required": [ + "dropdownOptionId" + ], + "additionalProperties": false + }, + "RankedDropdownValueUpdate": { + "title": "RankedDropdownValueUpdate", + "type": "object", + "properties": { + "type": { + "description": "The type of value", + "type": "string", + "const": "ranked-dropdown" + }, + "data": { + "oneOf": [ + { + "type": "null" + }, + { + "$ref": "#/components/schemas/RankedDropdownReference" + } + ] + } + }, + "required": [ + "data", + "type" + ] + }, + "FieldValueUpdate": { + "title": "FieldValueUpdate", + "oneOf": [ + { + "$ref": "#/components/schemas/CompaniesValueUpdate" + }, + { + "$ref": "#/components/schemas/CompanyValueUpdate" + }, + { + "$ref": "#/components/schemas/DateValue" + }, + { + "$ref": "#/components/schemas/DropdownValueUpdate" + }, + { + "$ref": "#/components/schemas/DropdownsValueUpdate" + }, + { + "$ref": "#/components/schemas/FloatValue" + }, + { + "$ref": "#/components/schemas/FloatsValue" + }, + { + "$ref": "#/components/schemas/LocationValue" + }, + { + "$ref": "#/components/schemas/LocationsValue" + }, + { + "$ref": "#/components/schemas/PersonValueUpdate" + }, + { + "$ref": "#/components/schemas/PersonsValueUpdate" + }, + { + "$ref": "#/components/schemas/RankedDropdownValueUpdate" + }, + { + "$ref": "#/components/schemas/TextValue" + }, + { + "$ref": "#/components/schemas/TextsValue" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "company-multi": "#/components/schemas/CompaniesValueUpdate", + "company": "#/components/schemas/CompanyValueUpdate", + "datetime": "#/components/schemas/DateValue", + "dropdown": "#/components/schemas/DropdownValueUpdate", + "dropdown-multi": "#/components/schemas/DropdownsValueUpdate", + "number": "#/components/schemas/FloatValue", + "number-multi": "#/components/schemas/FloatsValue", + "location": "#/components/schemas/LocationValue", + "location-multi": "#/components/schemas/LocationsValue", + "person": "#/components/schemas/PersonValueUpdate", + "person-multi": "#/components/schemas/PersonsValueUpdate", + "ranked-dropdown": "#/components/schemas/RankedDropdownValueUpdate", + "filterable-text": "#/components/schemas/TextValue", + "filterable-text-multi": "#/components/schemas/TextsValue", + "text": "#/components/schemas/TextValue" + } + }, + "examples": [ + { + "type": "location", + "data": { + "continent": "North America", + "country": "United States", + "streetAddress": "1 Main Street", + "city": "San Francisco", + "state": "California" + } + } + ] + }, + "ListEntryBatchOperationUpdateFields": { + "title": "ListEntryBatchOperationUpdateFields", + "description": "Update multiple field values.", + "type": "object", + "properties": { + "operation": { + "type": "string", + "const": "update-fields" + }, + "updates": { + "type": "array", + "maxItems": 100, + "items": { + "type": "object", + "properties": { + "id": { + "description": "The field's unique identifier.", + "type": "string", + "examples": [ + "field-105" + ] + }, + "value": { + "$ref": "#/components/schemas/FieldValueUpdate" + } + }, + "required": [ + "id" + ] + } + } + }, + "required": [ + "operation", + "updates" + ] + }, + "ListEntryBatchOperationRequest": { + "title": "ListEntryBatchOperationRequest", + "oneOf": [ + { + "$ref": "#/components/schemas/ListEntryBatchOperationUpdateFields" + } + ], + "discriminator": { + "propertyName": "operation", + "mapping": { + "update-fields": "#/components/schemas/ListEntryBatchOperationUpdateFields" + } + } + }, + "ListEntryBatchOperations": { + "title": "ListEntryBatchOperations", + "type": "string", + "enum": [ + "update-fields" + ] + }, + "ListEntryBatchOperationResponse": { + "title": "ListEntryBatchOperationResponse", + "type": "object", + "properties": { + "operation": { + "$ref": "#/components/schemas/ListEntryBatchOperations" + } + } + }, + "FieldUpdate": { + "title": "FieldUpdate", + "type": "object", + "properties": { + "value": { + "$ref": "#/components/schemas/FieldValueUpdate" + } + }, + "examples": [ + { + "value": { + "data": { + "continent": "North America", + "country": "United States", + "streetAddress": "1 Main Street", + "city": "San Francisco", + "state": "California" + }, + "type": "location" + } + } + ], + "additionalProperties": false + }, + "SavedView": { + "title": "SavedView", + "description": "SavedView model", + "type": "object", + "properties": { + "id": { + "description": "The saved view's unique identifier", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 28 + ] + }, + "name": { + "description": "The saved view's name", + "type": "string", + "examples": [ + "my interesting companies" + ] + }, + "type": { + "description": "The type for this saved view", + "type": "string", + "enum": [ + "sheet", + "board", + "dashboard" + ], + "examples": [ + "sheet" + ] + }, + "createdAt": { + "description": "The date that the saved view was created", + "type": "string", + "format": "date-time", + "examples": [ + "2023-01-01T00:00:00Z" + ] + } + }, + "required": [ + "createdAt", + "id", + "name", + "type" + ], + "additionalProperties": false, + "examples": [ + { + "createdAt": "2023-01-01T00:00:00Z", + "name": "my interesting companies", + "id": 28, + "type": "sheet" + } + ] + }, + "SavedViewPaged": { + "title": "SavedViewPaged", + "description": "SavedViewPaged model", + "type": "object", + "properties": { + "data": { + "description": "A page of SavedView results", + "type": "array", + "items": { + "$ref": "#/components/schemas/SavedView" + }, + "maxItems": 100 + }, + "pagination": { + "$ref": "#/components/schemas/Pagination" + } + }, + "required": [ + "data", + "pagination" + ], + "additionalProperties": false, + "examples": [ + { + "pagination": { + "prevUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgYmVmb3JlOjo6Nw", + "nextUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgIGFmdGVyOjo6NA" + }, + "data": [ + { + "createdAt": "2023-01-01T00:00:00Z", + "name": "my interesting companies", + "id": 28, + "type": "sheet" + }, + { + "createdAt": "2023-01-01T00:00:00Z", + "name": "my interesting companies", + "id": 28, + "type": "sheet" + } + ] + } + ] + }, + "interactions.Meeting": { + "title": "interactions.Meeting", + "type": "object", + "properties": { + "id": { + "description": "The meeting's unique identifier", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 1 + ] + }, + "loggingType": { + "description": "Indicates how the interaction was added to Affinity: either manually by a user ('manual') or automatically through Affinity's capture process ('automated').", + "type": "string", + "enum": [ + "automated", + "manual" + ], + "examples": [ + "automated" + ] + }, + "title": { + "description": "The meeting's title", + "type": [ + "string", + "null" + ], + "examples": [ + "Example title" + ] + }, + "startTime": { + "description": "The timestamp of when the meeting starts", + "type": "string", + "format": "date-time", + "examples": [ + "2023-01-01T00:00:00Z" + ] + }, + "endTime": { + "description": "The timestamp of when the meeting ends", + "type": [ + "string", + "null" + ], + "format": "date-time", + "examples": [ + "2023-01-01T00:00:00Z" + ] + }, + "allDay": { + "description": "Whether the meeting is all day", + "type": "boolean", + "examples": [ + false + ] + }, + "creator": { + "description": "The person who created the meeting", + "oneOf": [ + { + "$ref": "#/components/schemas/Attendee" + }, + { + "type": "null" + } + ] + }, + "organizer": { + "description": "The person who organized the meeting", + "oneOf": [ + { + "$ref": "#/components/schemas/Attendee" + }, + { + "type": "null" + } + ] + }, + "createdAt": { + "description": "The timestamp of when the meeting was created", + "type": "string", + "format": "date-time", + "examples": [ + "2023-01-01T00:00:00Z" + ] + }, + "updatedAt": { + "description": "The timestamp of when the meeting was updated", + "type": [ + "string", + "null" + ], + "format": "date-time", + "examples": [ + "2023-01-01T00:00:00Z" + ] + }, + "attendeesPreview": { + "description": "A preview of the attendees in the meeting", + "$ref": "#/components/schemas/AttendeesPreview" + } + }, + "required": [ + "id", + "loggingType", + "title", + "startTime", + "endTime", + "allDay", + "creator", + "organizer", + "createdAt", + "updatedAt", + "attendeesPreview" + ], + "additionalProperties": false + }, + "interactions.MeetingPaged": { + "title": "interactions.MeetingPaged", + "description": "MeetingPaged model", + "type": "object", + "properties": { + "data": { + "description": "A page of Meeting results", + "type": "array", + "items": { + "$ref": "#/components/schemas/interactions.Meeting" + }, + "maxItems": 100 + }, + "pagination": { + "$ref": "#/components/schemas/PaginationWithTotalCount" + } + }, + "required": [ + "data", + "pagination" + ], + "additionalProperties": false + }, + "CompanyDataPaged": { + "x-stability-level": "beta", + "title": "CompanyDataPaged", + "description": "CompanyDataPaged model", + "type": "object", + "properties": { + "data": { + "description": "A page of Company results", + "type": "array", + "items": { + "$ref": "#/components/schemas/CompanyData" + }, + "maxItems": 100 + }, + "pagination": { + "$ref": "#/components/schemas/Pagination" + } + }, + "required": [ + "data", + "pagination" + ], + "additionalProperties": false, + "examples": [ + { + "pagination": { + "prevUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgYmVmb3JlOjo6Nw", + "nextUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgIGFmdGVyOjo6NA" + }, + "data": [ + { + "domain": "acme.co", + "name": "Acme", + "id": 1 + }, + { + "domain": "acme.co", + "name": "Acme", + "id": 1 + } + ] + } + ] + }, + "OpportunityPaged": { + "title": "OpportunityPaged", + "description": "OpportunityPaged model", + "type": "object", + "properties": { + "data": { + "description": "A page of Opportunity results", + "type": "array", + "items": { + "$ref": "#/components/schemas/Opportunity" + }, + "maxItems": 100 + }, + "pagination": { + "$ref": "#/components/schemas/Pagination" + } + }, + "required": [ + "data", + "pagination" + ], + "additionalProperties": false, + "examples": [ + { + "pagination": { + "prevUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgYmVmb3JlOjo6Nw", + "nextUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgIGFmdGVyOjo6NA" + }, + "data": [ + { + "listId": 1, + "name": "Acme Upsell $10k", + "id": 1 + }, + { + "listId": 1, + "name": "Acme Upsell $10k", + "id": 1 + } + ] + } + ] + }, + "PersonDataPaged": { + "x-stability-level": "beta", + "title": "PersonDataPaged", + "description": "PersonDataPaged model", + "type": "object", + "properties": { + "data": { + "description": "A page of Person results", + "type": "array", + "items": { + "$ref": "#/components/schemas/PersonData" + }, + "maxItems": 100 + }, + "pagination": { + "$ref": "#/components/schemas/Pagination" + } + }, + "required": [ + "data", + "pagination" + ], + "additionalProperties": false, + "examples": [ + { + "pagination": { + "prevUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgYmVmb3JlOjo6Nw", + "nextUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgIGFmdGVyOjo6NA" + }, + "data": [ + { + "firstName": "Jane", + "lastName": "Doe", + "id": 1, + "type": "internal", + "primaryEmailAddress": "jane.doe@acme.co" + }, + { + "firstName": "Jane", + "lastName": "Doe", + "id": 1, + "type": "internal", + "primaryEmailAddress": "jane.doe@acme.co" + } + ] + } + ] + }, + "notes.Reply": { + "x-stability-level": "beta", + "title": "notes.Reply", + "description": "A Reply to a Note, created by a User or AI Notetaker.", + "oneOf": [ + { + "$ref": "#/components/schemas/notes.UserReplyNote" + }, + { + "$ref": "#/components/schemas/notes.AiNotetakerReplyNote" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "user-reply": "#/components/schemas/notes.UserReplyNote", + "ai-notetaker-reply": "#/components/schemas/notes.AiNotetakerReplyNote" + } + } + }, + "notes.RepliesPaged": { + "x-stability-level": "beta", + "title": "notes.RepliesPaged", + "description": "Replies for a Note", + "type": "object", + "properties": { + "data": { + "description": "A page of Note Replies", + "type": "array", + "items": { + "$ref": "#/components/schemas/notes.Reply" + }, + "maxItems": 100 + }, + "pagination": { + "$ref": "#/components/schemas/PaginationWithTotalCount" + } + }, + "required": [ + "data", + "pagination" + ] + }, + "PersonMergeState": { + "x-stability-level": "beta", + "title": "PersonMergeState", + "description": "Entity representing the state of an individual person merge", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for the merge", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 12345 + ] + }, + "status": { + "description": "Current status of the merge", + "type": "string", + "enum": [ + "in-progress", + "success", + "failed" + ], + "examples": [ + "success" + ] + }, + "taskId": { + "description": "Identifier for the task this merge belongs to", + "type": "string", + "format": "uuid", + "examples": [ + "789e0123-e45b-67c8-d901-234567890123" + ] + }, + "startedAt": { + "description": "Timestamp when the merge started", + "type": "string", + "format": "date-time", + "examples": [ + "2025-06-03T10:30:00Z" + ] + }, + "primaryPersonId": { + "description": "ID of the primary person that other profiles were merged into", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 12345 + ] + }, + "duplicatePersonId": { + "description": "ID of the duplicate person that was merged into the primary person", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 67890 + ] + }, + "completedAt": { + "description": "Timestamp when the merge completed (success or failure)", + "type": [ + "string", + "null" + ], + "format": "date-time", + "examples": [ + "2025-06-03T10:32:15Z", + null + ] + }, + "errorMessage": { + "description": "Error message if the merge failed", + "type": [ + "string", + "null" + ], + "examples": [ + "Primary person not found", + null + ] + } + }, + "required": [ + "id", + "status", + "taskId", + "startedAt", + "primaryPersonId", + "duplicatePersonId", + "completedAt", + "errorMessage" + ], + "additionalProperties": false + }, + "PersonMergeStatePaged": { + "x-stability-level": "beta", + "title": "PersonMergeStatePaged", + "description": "Paginated person merge states", + "type": "object", + "properties": { + "data": { + "description": "Array of person merge states", + "type": "array", + "maxItems": 100, + "items": { + "$ref": "#/components/schemas/PersonMergeState" + } + }, + "pagination": { + "$ref": "#/components/schemas/Pagination" + } + }, + "required": [ + "data", + "pagination" + ], + "additionalProperties": false + }, + "PersonMergeRequest": { + "x-stability-level": "beta", + "title": "PersonMergeRequest", + "description": "Request body for initiating a person merge", + "type": "object", + "properties": { + "primaryPersonId": { + "description": "The ID of the person profile that will be kept after the merge. All data from the duplicate person will be merged into this person.", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 12345 + ] + }, + "duplicatePersonId": { + "description": "The ID of the person profile that will be merged and then deleted. All data from this person will be transferred to the primary person.", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "examples": [ + 67890 + ] + } + }, + "required": [ + "primaryPersonId", + "duplicatePersonId" + ], + "additionalProperties": false + }, + "PersonMergeResponse": { + "x-stability-level": "beta", + "title": "PersonMergeResponse", + "description": "Response body for initiating a person merge", + "type": "object", + "properties": { + "taskUrl": { + "description": "URL to check the status of the merge task", + "type": "string", + "format": "uri", + "examples": [ + "https://api.affinit.com/tasks/person-merges/123e4567-e89b-12d3-a456-426614174000" + ] + } + }, + "required": [ + "taskUrl" + ], + "additionalProperties": false + }, + "PersonPaged": { + "title": "PersonPaged", + "description": "PersonPaged model", + "type": "object", + "properties": { + "data": { + "description": "A page of Person results", + "type": "array", + "items": { + "$ref": "#/components/schemas/Person" + }, + "maxItems": 100 + }, + "pagination": { + "$ref": "#/components/schemas/Pagination" + } + }, + "required": [ + "data", + "pagination" + ], + "additionalProperties": false, + "examples": [ + { + "pagination": { + "prevUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgYmVmb3JlOjo6Nw", + "nextUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgIGFmdGVyOjo6NA" + }, + "data": [ + { + "firstName": "Jane", + "lastName": "Doe", + "emailAddresses": [ + "jane.doe@acme.co", + "janedoe@gmail.com" + ], + "id": 1, + "type": "internal", + "fields": [ + { + "enrichmentSource": "affinity-data", + "name": "Location", + "id": "affinity-data-location", + "type": "enriched", + "value": { + "data": { + "continent": "North America", + "country": "United States", + "streetAddress": "1 Main Street", + "city": "San Francisco", + "state": "California" + }, + "type": "location" + } + }, + { + "enrichmentSource": "affinity-data", + "name": "Location", + "id": "affinity-data-location", + "type": "enriched", + "value": { + "data": { + "continent": "North America", + "country": "United States", + "streetAddress": "1 Main Street", + "city": "San Francisco", + "state": "California" + }, + "type": "location" + } + } + ], + "primaryEmailAddress": "jane.doe@acme.co" + }, + { + "firstName": "Jane", + "lastName": "Doe", + "emailAddresses": [ + "jane.doe@acme.co", + "janedoe@gmail.com" + ], + "id": 1, + "type": "internal", + "fields": [ + { + "enrichmentSource": "affinity-data", + "name": "Location", + "id": "affinity-data-location", + "type": "enriched", + "value": { + "data": { + "continent": "North America", + "country": "United States", + "streetAddress": "1 Main Street", + "city": "San Francisco", + "state": "California" + }, + "type": "location" + } + }, + { + "enrichmentSource": "affinity-data", + "name": "Location", + "id": "affinity-data-location", + "type": "enriched", + "value": { + "data": { + "continent": "North America", + "country": "United States", + "streetAddress": "1 Main Street", + "city": "San Francisco", + "state": "California" + }, + "type": "location" + } + } + ], + "primaryEmailAddress": "jane.doe@acme.co" + } + ] + } + ] + }, + "CompanyMergeTask": { + "title": "CompanyMergeTask", + "description": "Company merge task details and status for batch operations", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this merge task", + "type": "string", + "format": "uuid", + "examples": [ + "123e4567-e89b-12d3-a456-426614174000" + ] + }, + "status": { + "description": "The current status of the batch operation", + "type": "string", + "enum": [ + "in-progress", + "success", + "failed" + ], + "examples": [ + "in-progress" + ] + }, + "resultsSummary": { + "description": "Summary of merges in this batch task", + "type": "object", + "properties": { + "total": { + "description": "Total number of merges in the batch", + "type": "integer", + "format": "int32", + "minimum": 0, + "maximum": 2147483647, + "examples": [ + 5 + ] + }, + "inProgress": { + "description": "Number of merges currently in progress", + "type": "integer", + "format": "int32", + "minimum": 0, + "maximum": 2147483647, + "examples": [ + 2 + ] + }, + "success": { + "description": "Number of successfully completed merges", + "type": "integer", + "format": "int32", + "minimum": 0, + "maximum": 2147483647, + "examples": [ + 2 + ] + }, + "failed": { + "description": "Number of failed merges", + "type": "integer", + "format": "int32", + "minimum": 0, + "maximum": 2147483647, + "examples": [ + 1 + ] + } + }, + "required": [ + "total", + "inProgress", + "success", + "failed" + ], + "additionalProperties": false + } + }, + "required": [ + "id", + "status", + "resultsSummary" + ], + "additionalProperties": false + }, + "CompanyMergeTaskPaged": { + "title": "CompanyMergeTaskPaged", + "description": "Paginated list of company merge tasks", + "type": "object", + "properties": { + "data": { + "description": "Array of company merge tasks", + "type": "array", + "maxItems": 100, + "items": { + "$ref": "#/components/schemas/CompanyMergeTask" + }, + "examples": [ + [ + { + "id": "123e4567-e89b-12d3-a456-426614174000", + "status": "success", + "resultsSummary": { + "total": 1, + "inProgress": 0, + "success": 1, + "failed": 0 + } + }, + { + "id": "456e7890-e12b-34c5-d678-901234567890", + "status": "failed", + "resultsSummary": { + "total": 1, + "inProgress": 0, + "success": 0, + "failed": 1 + } + } + ] + ] + }, + "pagination": { + "$ref": "#/components/schemas/Pagination" + } + }, + "required": [ + "data", + "pagination" + ], + "additionalProperties": false + }, + "PersonMergeTask": { + "x-stability-level": "beta", + "title": "PersonMergeTask", + "description": "Person merge task details and status for batch operations", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this merge task", + "type": "string", + "format": "uuid", + "examples": [ + "123e4567-e89b-12d3-a456-426614174000" + ] + }, + "status": { + "description": "The current status of the batch operation", + "type": "string", + "enum": [ + "in-progress", + "success", + "failed" + ], + "examples": [ + "in-progress" + ] + }, + "resultsSummary": { + "description": "Summary of merges in this batch task", + "type": "object", + "properties": { + "total": { + "description": "Total number of merges in the batch", + "type": "integer", + "format": "int32", + "minimum": 0, + "maximum": 2147483647, + "examples": [ + 5 + ] + }, + "inProgress": { + "description": "Number of merges currently in progress", + "type": "integer", + "format": "int32", + "minimum": 0, + "maximum": 2147483647, + "examples": [ + 2 + ] + }, + "success": { + "description": "Number of successfully completed merges", + "type": "integer", + "format": "int32", + "minimum": 0, + "maximum": 2147483647, + "examples": [ + 2 + ] + }, + "failed": { + "description": "Number of failed merges", + "type": "integer", + "format": "int32", + "minimum": 0, + "maximum": 2147483647, + "examples": [ + 1 + ] + } + }, + "required": [ + "total", + "inProgress", + "success", + "failed" + ], + "additionalProperties": false + } + }, + "required": [ + "id", + "status", + "resultsSummary" + ], + "additionalProperties": false + }, + "PersonMergeTaskPaged": { + "x-stability-level": "beta", + "title": "PersonMergeTaskPaged", + "description": "Paginated person merge tasks", + "type": "object", + "properties": { + "data": { + "description": "Array of person merge tasks", + "type": "array", + "maxItems": 100, + "items": { + "$ref": "#/components/schemas/PersonMergeTask" + }, + "examples": [ + [ + { + "id": "123e4567-e89b-12d3-a456-426614174000", + "status": "success", + "resultsSummary": { + "total": 1, + "inProgress": 0, + "success": 1, + "failed": 0 + } + }, + { + "id": "456e7890-e12b-34c5-d678-901234567890", + "status": "failed", + "resultsSummary": { + "total": 1, + "inProgress": 0, + "success": 0, + "failed": 1 + } + } + ] + ] + }, + "pagination": { + "$ref": "#/components/schemas/Pagination" + } + }, + "required": [ + "data", + "pagination" + ], + "additionalProperties": false + } + }, + "responses": { + "400": { + "description": "Bad Request", + "content": { + "application/json": { + "schema": { + "title": "responses.400", + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/BadRequestError" + }, + { + "$ref": "#/components/schemas/ValidationError" + } + ], + "discriminator": { + "propertyName": "code", + "mapping": { + "bad-request": "#/components/schemas/BadRequestError", + "validation": "#/components/schemas/ValidationError" + } + } + } + } + }, + "required": [ + "errors" + ], + "additionalProperties": false + } + } + }, + "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" + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthorizationErrors" + } + } + }, + "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" + } + } + }, + "404": { + "description": "Not Found", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/NotFoundErrors" } - } - }, - "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" + } + }, + "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" + } + } + }, + "default": { + "description": "Errors", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Errors" + } + } + }, + "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" + } + } + } + }, + "examples": { + "merges-list": { + "x-stability-level": "beta", + "summary": "List of company merges", + "description": "Example response showing multiple company merges with different statuses", + "value": { + "data": [ + { + "id": 12, + "status": "success", + "taskId": "789e0123-e45b-67c8-d901-234567890123", + "startedAt": "2025-06-03T10:30:00Z", + "primaryCompanyId": 12345, + "duplicateCompanyId": 67890, + "completedAt": "2025-06-03T10:32:15Z", + "errorMessage": null + }, + { + "id": 13, + "status": "failed", + "taskId": "456e7890-1234-5678-9012-345678901234", + "startedAt": "2025-06-03T09:15:00Z", + "primaryCompanyId": 54321, + "duplicateCompanyId": 98765, + "completedAt": "2025-06-03T09:16:30Z", + "errorMessage": "Primary company not found" + } + ], + "pagination": { + "nextUrl": "https://api.affinity.co/v2/companies/merge?cursor=eyJpZCI6NDU2ZTc4OTAtZTEyYi0zNGM1LWQ2NzgtOTAxMjM0NTY3ODkwfQ==", + "prevUrl": null + } + } + }, + "merge-companies": { + "x-stability-level": "beta", + "summary": "Merge two company profiles", + "description": "Example request to merge a duplicate company profile into a primary company profile. The primary company (ID 12345) will be kept and all data from the duplicate company (ID 67890) will be merged into it.", + "value": { + "primaryCompanyId": 12345, + "duplicateCompanyId": 67890 + } + }, + "merge-initiated": { + "x-stability-level": "beta", + "summary": "Merge task initiated", + "description": "Response when a company merge task has been accepted for processing. The task ID can be used to track the progress of the merge task.", + "value": { + "taskUrl": "https://api.affinity.co/v2/tasks/company-merges/123e4567-e89b-12d3-a456-426614174000" + } + }, + "succeeded-merge": { + "x-stability-level": "beta", + "summary": "Succeeded company merge", + "description": "Example of a successful company merge", + "value": { + "id": 12345, + "status": "success", + "taskId": "1ac19acd-674c-49a0-819a-cd674cc9a042", + "startedAt": "2025-06-03T10:30:00Z", + "primaryCompanyId": 12345, + "duplicateCompanyId": 67890, + "completedAt": "2025-06-03T10:32:15Z", + "errorMessage": null + } + }, + "failed-merge": { + "x-stability-level": "beta", + "summary": "Failed company merge", + "description": "Example of a failed company merge with error details", + "value": { + "id": 67890, + "status": "failed", + "taskId": "789e0123-e45b-67c8-d901-234567890123", + "startedAt": "2025-06-03T09:15:00Z", + "primaryCompanyId": 54321, + "duplicateCompanyId": 98765, + "completedAt": "2025-06-03T09:16:30Z", + "errorMessage": "Primary company not found" + } + }, + "in-progress-merge": { + "x-stability-level": "beta", + "summary": "In-progress company merge", + "description": "Example of a company merge currently being processed", + "value": { + "id": 98765, + "status": "in-progress", + "taskId": "456e7890-e12b-34c5-d678-901234567890", + "startedAt": "2025-06-03T11:45:00Z", + "primaryCompanyId": 24680, + "duplicateCompanyId": 13579, + "completedAt": null, + "errorMessage": null + } + }, + "success": { + "value": { + "data": [ + { + "id": 1, + "name": "My Companies", + "type": "company", + "isPublic": false, + "ownerId": 1, + "creatorId": 1 + }, + { + "id": 2, + "name": "My Persons", + "type": "person", + "isPublic": false, + "ownerId": 1, + "creatorId": 1 + }, + { + "id": 3, + "name": "My Opportunities", + "type": "opportunity", + "isPublic": false, + "ownerId": 1, + "creatorId": 1 + } + ], + "pagination": { + "prevUrl": "https://api.affinity.co/v2/lists?cursor=ICAgICAgYmVmb3JlOjo6Nw", + "nextUrl": "https://api.affinity.co/v2/lists?cursor=ICAgICAgIGFmdGVyOjo6NA" + } + } + }, + "company-list": { + "description": "Example Company list.", + "value": { + "id": 1, + "name": "My Companies", + "type": "company", + "isPublic": false, + "ownerId": 1, + "creatorId": 1 + } + }, + "opportunity-list": { + "description": "Example Opportunity list.", + "value": { + "id": 3, + "name": "My Opportunities", + "type": "opportunity", + "isPublic": false, + "ownerId": 1, + "creatorId": 1 + } + }, + "person-list": { + "description": "Example Person list.", + "value": { + "id": 2, + "name": "My Persons", + "type": "person", + "isPublic": false, + "ownerId": 1, + "creatorId": 1 + } + }, + "company-list-2": { + "description": "Example response on a Company list.", + "value": { + "data": [ + { + "id": "affinity-data-description", + "name": "Description", + "type": "enriched", + "valueType": "text", + "enrichmentSource": "affinity-data" + }, + { + "id": "affinity-data-industry", + "name": "Industry", + "type": "enriched", + "valueType": "filterable-text-multi", + "enrichmentSource": "affinity-data" + }, + { + "id": "affinity-data-investment-stage", + "name": "Investment Stage", + "type": "enriched", + "valueType": "filterable-text", + "enrichmentSource": "affinity-data" + }, + { + "id": "affinity-data-investors", + "name": "Investors", + "type": "enriched", + "valueType": "filterable-text-multi", + "enrichmentSource": "affinity-data" + }, + { + "id": "affinity-data-last-funding-amount", + "name": "Last Funding Amount (USD)", + "type": "enriched", + "valueType": "number", + "enrichmentSource": "affinity-data" + }, + { + "id": "affinity-data-last-funding-date", + "name": "Last Funding Date", + "type": "enriched", + "valueType": "datetime", + "enrichmentSource": "affinity-data" + }, + { + "id": "affinity-data-linkedin-url", + "name": "LinkedIn URL", + "type": "enriched", + "valueType": "text", + "enrichmentSource": "affinity-data" + }, + { + "id": "affinity-data-location", + "name": "Location", + "type": "enriched", + "valueType": "location", + "enrichmentSource": "affinity-data" + }, + { + "id": "affinity-data-number-of-employees", + "name": "Number of Employees", + "type": "enriched", + "valueType": "number", + "enrichmentSource": "affinity-data" + }, + { + "id": "affinity-data-total-funding-amount", + "name": "Total Funding Amount (USD)", + "type": "enriched", + "valueType": "number", + "enrichmentSource": "affinity-data" + }, + { + "id": "affinity-data-year-founded", + "name": "Year Founded", + "type": "enriched", + "valueType": "number", + "enrichmentSource": "affinity-data" + }, + { + "id": "field-1", + "name": "Custom global field", + "type": "global", + "valueType": "text", + "enrichmentSource": null + }, + { + "id": "field-2", + "name": "Custom list field", + "type": "list", + "valueType": "text", + "enrichmentSource": null + }, + { + "id": "first-chat-message", + "name": "First Chat Message", + "type": "relationship-intelligence", + "valueType": "interaction", + "enrichmentSource": null + }, + { + "id": "first-email", + "name": "First Email", + "type": "relationship-intelligence", + "valueType": "interaction", + "enrichmentSource": null + }, + { + "id": "first-event", + "name": "First Event", + "type": "relationship-intelligence", + "valueType": "interaction", + "enrichmentSource": null + }, + { + "id": "last-chat-message", + "name": "Last Chat Message", + "type": "relationship-intelligence", + "valueType": "interaction", + "enrichmentSource": null + }, + { + "id": "last-contact", + "name": "Last Contact", + "type": "relationship-intelligence", + "valueType": "interaction", + "enrichmentSource": null + }, + { + "id": "last-email", + "name": "Last Email", + "type": "relationship-intelligence", + "valueType": "interaction", + "enrichmentSource": null + }, + { + "id": "last-event", + "name": "Last Event", + "type": "relationship-intelligence", + "valueType": "interaction", + "enrichmentSource": null + }, + { + "id": "next-event", + "name": "Next Event", + "type": "relationship-intelligence", + "valueType": "interaction", + "enrichmentSource": null + }, + { + "id": "source-of-introduction", + "name": "Source of Introduction", + "type": "relationship-intelligence", + "valueType": "person", + "enrichmentSource": null + } + ], + "pagination": { + "prevUrl": "https://api.affinity.co/v2/lists/1/fields?cursor=ICAgICAgYmVmb3JlOjo6Nw", + "nextUrl": "https://api.affinity.co/v2/lists/1/fields?cursor=ICAgICAgIGFmdGVyOjo6NA" + } + } + }, + "person-list-2": { + "description": "Example response on a Person list.", + "value": { + "data": [ + { + "id": "affinity-data-current-job-title", + "name": "Current Job Title", + "type": "enriched", + "valueType": "filterable-text", + "enrichmentSource": "affinity-data" + }, + { + "id": "affinity-data-current-organization", + "name": "Current Organization", + "type": "enriched", + "valueType": "company", + "enrichmentSource": "affinity-data" + }, + { + "id": "affinity-data-industry", + "name": "Industry", + "type": "enriched", + "valueType": "filterable-text-multi", + "enrichmentSource": "affinity-data" + }, + { + "id": "affinity-data-job-titles", + "name": "Job Titles", + "type": "enriched", + "valueType": "filterable-text-multi", + "enrichmentSource": "affinity-data" + }, + { + "id": "affinity-data-location", + "name": "Location", + "type": "enriched", + "valueType": "location", + "enrichmentSource": "affinity-data" + }, + { + "id": "affinity-data-linkedin-url", + "name": "LinkedIn URL", + "type": "enriched", + "valueType": "text", + "enrichmentSource": "affinity-data" + }, + { + "id": "affinity-data-phone-number", + "name": "Phone Number", + "type": "enriched", + "valueType": "filterable-text-multi", + "enrichmentSource": "affinity-data" + }, + { + "id": "companies", + "name": "Organizations", + "type": "list", + "valueType": "company-multi", + "enrichmentSource": null + }, + { + "id": "field-1", + "name": "Custom global field", + "type": "global", + "valueType": "text", + "enrichmentSource": null + }, + { + "id": "field-2", + "name": "Custom list field", + "type": "list", + "valueType": "text", + "enrichmentSource": null + }, + { + "id": "first-chat-message", + "name": "First Chat Message", + "type": "relationship-intelligence", + "valueType": "interaction", + "enrichmentSource": null + }, + { + "id": "first-email", + "name": "First Email", + "type": "relationship-intelligence", + "valueType": "interaction", + "enrichmentSource": null + }, + { + "id": "first-event", + "name": "First Event", + "type": "relationship-intelligence", + "valueType": "interaction", + "enrichmentSource": null + }, + { + "id": "last-chat-message", + "name": "Last Chat Message", + "type": "relationship-intelligence", + "valueType": "interaction", + "enrichmentSource": null + }, + { + "id": "last-contact", + "name": "Last Contact", + "type": "relationship-intelligence", + "valueType": "interaction", + "enrichmentSource": null + }, + { + "id": "last-email", + "name": "Last Email", + "type": "relationship-intelligence", + "valueType": "interaction", + "enrichmentSource": null + }, + { + "id": "last-event", + "name": "Last Event", + "type": "relationship-intelligence", + "valueType": "interaction", + "enrichmentSource": null + }, + { + "id": "next-event", + "name": "Next Event", + "type": "relationship-intelligence", + "valueType": "interaction", + "enrichmentSource": null + }, + { + "id": "source-of-introduction", + "name": "Source of Introduction", + "type": "relationship-intelligence", + "valueType": "person", + "enrichmentSource": null + } + ], + "pagination": { + "prevUrl": "https://api.affinity.co/v2/lists/2/fields?cursor=ICAgICAgYmVmb3JlOjo6Nw", + "nextUrl": "https://api.affinity.co/v2/lists/2/fields?cursor=ICAgICAgIGFmdGVyOjo6NA" } } }, - "default": { - "description": "Errors", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Errors" - } - } - }, - "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" - } - } - } - }, - "examples": { - "success": { + "opportunity-list-2": { + "description": "Example response on an Opportunity list.", "value": { "data": [ { - "id": 1, - "name": "My Companies", - "type": "company", - "isPublic": false, - "ownerId": 1, - "creatorId": 1 + "id": "companies", + "name": "Organizations", + "type": "list", + "valueType": "company-multi", + "enrichmentSource": null }, { - "id": 2, - "name": "My Persons", - "type": "person", - "isPublic": false, - "ownerId": 1, - "creatorId": 1 + "id": "field-2", + "name": "Custom list field", + "type": "list", + "valueType": "text", + "enrichmentSource": null }, { - "id": 3, - "name": "My Opportunities", - "type": "opportunity", - "isPublic": false, - "ownerId": 1, - "creatorId": 1 + "id": "first-chat-message", + "name": "First Chat Message", + "type": "relationship-intelligence", + "valueType": "interaction", + "enrichmentSource": null + }, + { + "id": "first-email", + "name": "First Email", + "type": "relationship-intelligence", + "valueType": "interaction", + "enrichmentSource": null + }, + { + "id": "first-event", + "name": "First Event", + "type": "relationship-intelligence", + "valueType": "interaction", + "enrichmentSource": null + }, + { + "id": "last-chat-message", + "name": "Last Chat Message", + "type": "relationship-intelligence", + "valueType": "interaction", + "enrichmentSource": null + }, + { + "id": "last-contact", + "name": "Last Contact", + "type": "relationship-intelligence", + "valueType": "interaction", + "enrichmentSource": null + }, + { + "id": "last-email", + "name": "Last Email", + "type": "relationship-intelligence", + "valueType": "interaction", + "enrichmentSource": null + }, + { + "id": "last-event", + "name": "Last Event", + "type": "relationship-intelligence", + "valueType": "interaction", + "enrichmentSource": null + }, + { + "id": "next-event", + "name": "Next Event", + "type": "relationship-intelligence", + "valueType": "interaction", + "enrichmentSource": null + }, + { + "id": "persons", + "name": "People", + "type": "list", + "valueType": "person-multi", + "enrichmentSource": null } ], "pagination": { - "prevUrl": "https://api.affinity.co/v2/lists?cursor=ICAgICAgYmVmb3JlOjo6Nw", - "nextUrl": "https://api.affinity.co/v2/lists?cursor=ICAgICAgIGFmdGVyOjo6NA" + "prevUrl": "https://api.affinity.co/v2/lists/3/fields?cursor=ICAgICAgYmVmb3JlOjo6Nw", + "nextUrl": "https://api.affinity.co/v2/lists/3/fields?cursor=ICAgICAgIGFmdGVyOjo6NA" } } }, - "company-list": { - "description": "Example Company list.", - "value": { - "id": 1, - "name": "My Companies", - "type": "company", - "isPublic": false, - "ownerId": 1, - "creatorId": 1 - } - }, - "opportunity-list": { - "description": "Example Opportunity list.", - "value": { - "id": 3, - "name": "My Opportunities", - "type": "opportunity", - "isPublic": false, - "ownerId": 1, - "creatorId": 1 - } - }, - "person-list": { - "description": "Example Person list.", - "value": { - "id": 2, - "name": "My Persons", - "type": "person", - "isPublic": false, - "ownerId": 1, - "creatorId": 1 - } - }, "company-list-enriched": { "description": "Example response on a Company list using `fieldTypes=enriched`.", "value": { @@ -7735,7 +12392,6 @@ } }, "company-list-enriched-2": { - "x-stability-level": "beta", "description": "Example response on a Company list using `fieldTypes=enriched`.", "value": { "id": 1, @@ -7880,7 +12536,6 @@ } }, "company-list-relationship-intelligence-2": { - "x-stability-level": "beta", "description": "Example response on a Company list using `fieldTypes=relationship-intelligence`.", "value": { "id": 1, @@ -8225,7 +12880,6 @@ } }, "company-list-global-and-list-2": { - "x-stability-level": "beta", "description": "Example response on a Company list using `fieldTypes=global&fieldTypes=list`.", "value": { "id": 1, @@ -8267,7 +12921,6 @@ } }, "company-list-enriched-3": { - "x-stability-level": "beta", "description": "Example response on a Company list using `types=enriched`.", "value": { "data": [ @@ -8402,7 +13055,6 @@ } }, "company-list-relationship-intelligence-3": { - "x-stability-level": "beta", "description": "Example response on a Company list using `types=relationship-intelligence`.", "value": { "data": [ @@ -8737,7 +13389,6 @@ } }, "company-list-global-and-list-3": { - "x-stability-level": "beta", "description": "Example response on a Company list using `types=global&fieldTypes=list`.", "value": { "data": [ @@ -8769,7 +13420,6 @@ } }, "update-fields": { - "x-stability-level": "beta", "description": "Example request for an `update-fields` operation.", "value": { "operation": "update-fields", @@ -8832,7 +13482,7 @@ "value": { "type": "location", "data": { - "streetAddress": "170 Columbus Ave", + "streetAddress": "1 Main Street", "city": "San Francisco", "state": "California", "country": "United States", @@ -8846,7 +13496,7 @@ "type": "location-multi", "data": [ { - "streetAddress": "170 Columbus Ave", + "streetAddress": "1 Main Street", "city": "San Francisco", "state": "California", "country": "United States", @@ -8923,14 +13573,12 @@ } }, "update-fields-2": { - "x-stability-level": "beta", "description": "Example response from an update-fields operation.", "value": { "operation": "update-fields" } }, "company": { - "x-stability-level": "beta", "description": "Example response on a field with a company value.", "value": { "id": "field-1", @@ -8948,7 +13596,6 @@ } }, "company-multi": { - "x-stability-level": "beta", "description": "Example response on a field with a company-multi value.", "value": { "id": "field-2", @@ -8973,7 +13620,6 @@ } }, "datetime": { - "x-stability-level": "beta", "description": "Example response on a field with a datetime value.", "value": { "id": "field-3", @@ -8987,7 +13633,6 @@ } }, "dropdown": { - "x-stability-level": "beta", "description": "Example response on a field with a dropdown value.", "value": { "id": "field-4", @@ -9004,7 +13649,6 @@ } }, "dropdown-multi": { - "x-stability-level": "beta", "description": "Example response on a field with a dropdown-multi value.", "value": { "id": "field-5", @@ -9027,7 +13671,6 @@ } }, "filterable-text": { - "x-stability-level": "beta", "description": "Example response on a field with a filterable-text value.", "value": { "id": "field-6", @@ -9041,7 +13684,6 @@ } }, "filterable-text-multi": { - "x-stability-level": "beta", "description": "Example response on a field with a filterable-text-multi value.", "value": { "id": "field-7", @@ -9058,7 +13700,6 @@ } }, "formula-number": { - "x-stability-level": "beta", "description": "Example response on a field with a formula-number value.", "value": { "id": "field-8", @@ -9074,7 +13715,6 @@ } }, "interaction": { - "x-stability-level": "beta", "description": "Example response on a field with a interaction value.", "value": { "id": "field-9", @@ -9117,7 +13757,6 @@ } }, "location": { - "x-stability-level": "beta", "description": "Example response on a field with a location value.", "value": { "id": "field-10", @@ -9127,7 +13766,7 @@ "value": { "type": "location", "data": { - "streetAddress": "170 Columbus Ave", + "streetAddress": "1 Main Street", "city": "San Francisco", "state": "California", "country": "United States", @@ -9137,7 +13776,6 @@ } }, "location-multi": { - "x-stability-level": "beta", "description": "Example response on a field with a location-multi value.", "value": { "id": "field-11", @@ -9148,7 +13786,7 @@ "type": "location-multi", "data": [ { - "streetAddress": "170 Columbus Ave", + "streetAddress": "1 Main Street", "city": "San Francisco", "state": "California", "country": "United States", @@ -9166,7 +13804,6 @@ } }, "number": { - "x-stability-level": "beta", "description": "Example response on a field with a number value.", "value": { "id": "field-12", @@ -9180,7 +13817,6 @@ } }, "number-multi": { - "x-stability-level": "beta", "description": "Example response on a field with a number-multi value.", "value": { "id": "field-13", @@ -9198,7 +13834,6 @@ } }, "person": { - "x-stability-level": "beta", "description": "Example response on a field with a person value.", "value": { "id": "field-14", @@ -9218,7 +13853,6 @@ } }, "person-multi": { - "x-stability-level": "beta", "description": "Example response on a field with a person-multi value.", "value": { "id": "field-15", @@ -9247,7 +13881,6 @@ } }, "ranked-dropdown": { - "x-stability-level": "beta", "description": "Example response on a field with a ranked-dropdown value.", "value": { "id": "field-16", @@ -9266,7 +13899,6 @@ } }, "text": { - "x-stability-level": "beta", "description": "Example response on a field with a text value.", "value": { "id": "field-17", @@ -9280,7 +13912,6 @@ } }, "company-2": { - "x-stability-level": "beta", "description": "Example response on a field with a company value.", "value": { "value": { @@ -9292,7 +13923,6 @@ } }, "company-multi-2": { - "x-stability-level": "beta", "description": "Example response on a field with a company-multi value.", "value": { "value": { @@ -9309,7 +13939,6 @@ } }, "datetime-2": { - "x-stability-level": "beta", "description": "Example response on a field with a datetime value.", "value": { "value": { @@ -9319,7 +13948,6 @@ } }, "dropdown-2": { - "x-stability-level": "beta", "description": "Example response on a field with a dropdown value.", "value": { "value": { @@ -9331,7 +13959,6 @@ } }, "dropdown-multi-2": { - "x-stability-level": "beta", "description": "Example response on a field with a dropdown-multi value.", "value": { "value": { @@ -9348,7 +13975,6 @@ } }, "filterable-text-2": { - "x-stability-level": "beta", "description": "Example response on a field with a filterable-text value.", "value": { "value": { @@ -9358,7 +13984,6 @@ } }, "filterable-text-multi-2": { - "x-stability-level": "beta", "description": "Example response on a field with a filterable-text-multi value.", "value": { "value": { @@ -9371,13 +13996,12 @@ } }, "location-2": { - "x-stability-level": "beta", "description": "Example response on a field with a location value.", "value": { "value": { "type": "location", "data": { - "streetAddress": "170 Columbus Ave", + "streetAddress": "1 Main Street", "city": "San Francisco", "state": "California", "country": "United States", @@ -9387,14 +14011,13 @@ } }, "location-multi-2": { - "x-stability-level": "beta", "description": "Example response on a field with a location-multi value.", "value": { "value": { "type": "location-multi", "data": [ { - "streetAddress": "170 Columbus Ave", + "streetAddress": "1 Main Street", "city": "San Francisco", "state": "California", "country": "United States", @@ -9412,7 +14035,6 @@ } }, "number-2": { - "x-stability-level": "beta", "description": "Example response on a field with a number value.", "value": { "value": { @@ -9422,7 +14044,6 @@ } }, "number-multi-2": { - "x-stability-level": "beta", "description": "Example response on a field with a number-multi value.", "value": { "value": { @@ -9436,7 +14057,6 @@ } }, "person-2": { - "x-stability-level": "beta", "description": "Example response on a field with a person value.", "value": { "value": { @@ -9448,7 +14068,6 @@ } }, "person-multi-2": { - "x-stability-level": "beta", "description": "Example response on a field with a person-multi value.", "value": { "value": { @@ -9465,7 +14084,6 @@ } }, "ranked-dropdown-2": { - "x-stability-level": "beta", "description": "Example response on a field with a ranked-dropdown value.", "value": { "value": { @@ -9477,7 +14095,6 @@ } }, "text-2": { - "x-stability-level": "beta", "description": "Example response on a field with a text value.", "value": { "value": { @@ -9486,403 +14103,900 @@ } } }, - "company-list-2": { - "description": "Example response on a Company list.", + "ai-notetaker": { + "x-stability-level": "beta", + "description": "Example response for AI Notetaker notes.", "value": { "data": [ { - "id": "affinity-data-description", - "name": "Description", - "type": "enriched", - "valueType": "text", - "enrichmentSource": "affinity-data" - }, - { - "id": "affinity-data-industry", - "name": "Industry", - "type": "enriched", - "valueType": "filterable-text-multi", - "enrichmentSource": "affinity-data" - }, - { - "id": "affinity-data-investment-stage", - "name": "Investment Stage", - "type": "enriched", - "valueType": "filterable-text", - "enrichmentSource": "affinity-data" - }, - { - "id": "affinity-data-investors", - "name": "Investors", - "type": "enriched", - "valueType": "filterable-text-multi", - "enrichmentSource": "affinity-data" - }, - { - "id": "affinity-data-last-funding-amount", - "name": "Last Funding Amount (USD)", - "type": "enriched", - "valueType": "number", - "enrichmentSource": "affinity-data" - }, - { - "id": "affinity-data-last-funding-date", - "name": "Last Funding Date", - "type": "enriched", - "valueType": "datetime", - "enrichmentSource": "affinity-data" - }, - { - "id": "affinity-data-linkedin-url", - "name": "LinkedIn URL", - "type": "enriched", - "valueType": "text", - "enrichmentSource": "affinity-data" - }, - { - "id": "affinity-data-location", - "name": "Location", - "type": "enriched", - "valueType": "location", - "enrichmentSource": "affinity-data" - }, - { - "id": "affinity-data-number-of-employees", - "name": "Number of Employees", - "type": "enriched", - "valueType": "number", - "enrichmentSource": "affinity-data" - }, - { - "id": "affinity-data-total-funding-amount", - "name": "Total Funding Amount (USD)", - "type": "enriched", - "valueType": "number", - "enrichmentSource": "affinity-data" + "id": 1, + "type": "ai-notetaker", + "content": { + "html": "

This is an AI Notetaker note!

" + }, + "creator": { + "id": 1, + "firstName": "Jane", + "lastName": "Doe", + "primaryEmailAddress": "jane.doe@acme.co", + "type": "internal" + }, + "mentions": [], + "createdAt": "2023-01-01T00:00:00Z", + "updatedAt": "2023-01-21T00:00:00Z" }, { - "id": "affinity-data-year-founded", - "name": "Year Founded", - "type": "enriched", - "valueType": "number", - "enrichmentSource": "affinity-data" - }, + "id": 2, + "type": "ai-notetaker", + "content": { + "html": "

This is another AI Notetaker note!

" + }, + "creator": { + "id": 1, + "firstName": "Jane", + "lastName": "Doe", + "primaryEmailAddress": "jane.doe@acme.co", + "type": "internal" + }, + "mentions": [], + "createdAt": "2024-01-01T00:00:00Z", + "updatedAt": "2024-01-21T00:00:00Z" + } + ], + "pagination": { + "prevUrl": "https://api.affinity.co/v2/notes?cursor=ICAgICAgYmVmb3JlOjo6Nw", + "nextUrl": "https://api.affinity.co/v2/notes?cursor=ICAgICAgIGFmdGVyOjo6NA" + } + } + }, + "entities": { + "x-stability-level": "beta", + "description": "Example response for entity notes.", + "value": { + "data": [ { - "id": "field-1", - "name": "Custom global field", - "type": "global", - "valueType": "text", - "enrichmentSource": null + "id": 1, + "type": "entities", + "content": { + "html": "

This is a note! John Doe

" + }, + "creator": { + "id": 1, + "firstName": "Jane", + "lastName": "Doe", + "primaryEmailAddress": "jane.doe@acme.co", + "type": "internal" + }, + "mentions": [ + { + "id": 1, + "type": "person", + "person": { + "id": 2, + "firstName": "John", + "lastName": "Doe", + "primaryEmailAddress": "john.doe@acme.co", + "type": "internal" + } + } + ], + "createdAt": "2023-01-01T00:00:00Z", + "updatedAt": "2023-01-21T00:00:00Z" }, { - "id": "field-2", - "name": "Custom list field", - "type": "list", - "valueType": "text", - "enrichmentSource": null - }, + "id": 2, + "type": "entities", + "content": { + "html": "

This is another note!

" + }, + "creator": { + "id": 1, + "firstName": "Jane", + "lastName": "Doe", + "primaryEmailAddress": "jane.doe@acme.co", + "type": "internal" + }, + "mentions": [], + "createdAt": "2024-01-01T00:00:00Z", + "updatedAt": "2024-01-21T00:00:00Z" + } + ], + "pagination": { + "prevUrl": "https://api.affinity.co/v2/notes?cursor=ICAgICAgYmVmb3JlOjo6Nw", + "nextUrl": "https://api.affinity.co/v2/notes?cursor=ICAgICAgIGFmdGVyOjo6NA" + } + } + }, + "interaction-2": { + "x-stability-level": "beta", + "description": "Example response for interaction notes.", + "value": { + "data": [ { - "id": "first-chat-message", - "name": "First Chat Message", - "type": "relationship-intelligence", - "valueType": "interaction", - "enrichmentSource": null + "id": 1, + "type": "interaction", + "content": { + "html": "

This is a call note!

Jane Doe" + }, + "creator": { + "id": 1, + "firstName": "Jane", + "lastName": "Doe", + "primaryEmailAddress": "jane.doe@acme.co", + "type": "internal" + }, + "mentions": [ + { + "id": 1, + "type": "person", + "person": { + "id": 1, + "firstName": "Jane", + "lastName": "Doe", + "primaryEmailAddress": "jane.doe@acme.co", + "type": "internal" + } + } + ], + "createdAt": "2023-01-01T00:00:00Z", + "updatedAt": "2023-01-21T00:00:00Z", + "interaction": { + "id": 1, + "type": "call" + } }, { - "id": "first-email", - "name": "First Email", - "type": "relationship-intelligence", - "valueType": "interaction", - "enrichmentSource": null + "id": 2, + "type": "interaction", + "content": { + "html": "

This is a meeting note!

" + }, + "creator": { + "id": 1, + "firstName": "Jane", + "lastName": "Doe", + "primaryEmailAddress": "jane.doe@acme.co", + "type": "internal" + }, + "mentions": [], + "createdAt": "2023-02-01T00:00:00Z", + "updatedAt": null, + "interaction": { + "id": 1, + "type": "meeting" + } }, { - "id": "first-event", - "name": "First Event", - "type": "relationship-intelligence", - "valueType": "interaction", - "enrichmentSource": null + "id": 3, + "type": "interaction", + "content": { + "html": "

This is an email note!

" + }, + "creator": { + "id": 1, + "firstName": "Jane", + "lastName": "Doe", + "primaryEmailAddress": "jane.doe@acme.co", + "type": "internal" + }, + "mentions": [], + "createdAt": "2023-02-01T00:00:00Z", + "updatedAt": null, + "interaction": { + "id": 1, + "type": "email" + } }, { - "id": "last-chat-message", - "name": "Last Chat Message", - "type": "relationship-intelligence", - "valueType": "interaction", - "enrichmentSource": null - }, + "id": 4, + "type": "interaction", + "content": { + "html": "

This is a chat message note!

" + }, + "creator": { + "id": 1, + "firstName": "Jane", + "lastName": "Doe", + "primaryEmailAddress": "jane.doe@acme.co", + "type": "internal" + }, + "mentions": [], + "createdAt": "2023-02-01T00:00:00Z", + "updatedAt": null, + "interaction": { + "id": 1, + "type": "chat-message" + } + } + ], + "pagination": { + "prevUrl": "https://api.affinity.co/v2/notes?cursor=ICAgICAgYmVmb3JlOjo6Nw", + "nextUrl": "https://api.affinity.co/v2/notes?cursor=ICAgICAgIGFmdGVyOjo6NA" + } + } + }, + "ai-notetaker-2": { + "x-stability-level": "beta", + "description": "Example response for an AI Notetaker note.", + "value": { + "id": 1, + "type": "ai-notetaker", + "content": { + "html": "

This is an AI Notetaker note!

" + }, + "creator": { + "id": 1, + "firstName": "Jane", + "lastName": "Doe", + "primaryEmailAddress": "jane.doe@acme.co", + "type": "internal" + }, + "mentions": [], + "createdAt": "2023-01-01T00:00:00Z", + "updatedAt": "2023-01-21T00:00:00Z" + } + }, + "ai-notetaker-reply": { + "x-stability-level": "beta", + "description": "Example response for an AI Notetaker note reply.", + "value": { + "id": 2, + "type": "ai-notetaker-reply", + "content": { + "html": "

This is an AI Notetaker reply note!

" + }, + "creator": { + "id": 1, + "firstName": "Jane", + "lastName": "Doe", + "primaryEmailAddress": "jane.doe@acme.co", + "type": "internal" + }, + "mentions": [], + "parent": { + "id": 1 + }, + "createdAt": "2023-01-01T00:00:00Z", + "updatedAt": "2023-01-21T00:00:00Z" + } + }, + "entities-2": { + "x-stability-level": "beta", + "description": "Example response for an entities note.", + "value": { + "id": 1, + "type": "entities", + "content": { + "html": "

This is a note! John Doe was mentioned.

" + }, + "creator": { + "id": 1, + "firstName": "Jane", + "lastName": "Doe", + "primaryEmailAddress": "jane.doe@acme.co", + "type": "internal" + }, + "mentions": [ { - "id": "last-contact", - "name": "Last Contact", - "type": "relationship-intelligence", - "valueType": "interaction", - "enrichmentSource": null - }, + "id": 1, + "type": "person", + "person": { + "id": 2, + "firstName": "John", + "lastName": "Doe", + "primaryEmailAddress": "john.doe@acme.co", + "type": "internal" + } + } + ], + "createdAt": "2023-01-01T00:00:00Z", + "updatedAt": "2023-01-21T00:00:00Z" + } + }, + "interaction-3": { + "x-stability-level": "beta", + "description": "Example response for an interaction note.", + "value": { + "id": 1, + "type": "interaction", + "content": { + "html": "

This is a note! John Doe was mentioned.

" + }, + "creator": { + "id": 1, + "firstName": "Jane", + "lastName": "Doe", + "primaryEmailAddress": "jane.doe@acme.co", + "type": "internal" + }, + "mentions": [ { - "id": "last-email", - "name": "Last Email", - "type": "relationship-intelligence", - "valueType": "interaction", - "enrichmentSource": null - }, + "id": 1, + "type": "person", + "person": { + "id": 2, + "firstName": "John", + "lastName": "Doe", + "primaryEmailAddress": "john.doe@acme.co", + "type": "internal" + } + } + ], + "createdAt": "2023-01-01T00:00:00Z", + "updatedAt": "2023-01-21T00:00:00Z", + "interaction": { + "id": 2, + "type": "call" + } + } + }, + "user-reply": { + "x-stability-level": "beta", + "description": "Example response for a user reply note.", + "value": { + "id": 2, + "type": "user-reply", + "content": { + "html": "

This reply note was added manually by a user. John Doe was mentioned.

" + }, + "creator": { + "id": 1, + "firstName": "Jane", + "lastName": "Doe", + "primaryEmailAddress": "jane.doe@acme.co", + "type": "internal" + }, + "mentions": [ { - "id": "last-event", - "name": "Last Event", - "type": "relationship-intelligence", - "valueType": "interaction", - "enrichmentSource": null - }, + "id": 1, + "type": "person", + "person": { + "id": 2, + "firstName": "John", + "lastName": "Doe", + "primaryEmailAddress": "john.doe@acme.co", + "type": "internal" + } + } + ], + "parent": { + "id": 1 + }, + "createdAt": "2023-01-01T00:00:00Z", + "updatedAt": "2023-01-21T00:00:00Z" + } + }, + "success-2": { + "x-stability-level": "beta", + "description": "Example response on fetching opportunities attached to a note.", + "value": { + "data": [ { - "id": "next-event", - "name": "Next Event", - "type": "relationship-intelligence", - "valueType": "interaction", - "enrichmentSource": null + "id": 1, + "name": "Opp Name", + "listId": 1000 }, { - "id": "source-of-introduction", - "name": "Source of Introduction", - "type": "relationship-intelligence", - "valueType": "person", - "enrichmentSource": null + "id": 2, + "name": "Another Opp Name", + "listId": 1001 } ], "pagination": { - "prevUrl": "https://api.affinity.co/v2/lists/1/fields?cursor=ICAgICAgYmVmb3JlOjo6Nw", - "nextUrl": "https://api.affinity.co/v2/lists/1/fields?cursor=ICAgICAgIGFmdGVyOjo6NA" + "prevUrl": "https://api.affinity.co/v2/notes/1/attached-opportunities?cursor=ICAgICAgYmVmb3JlOjo6Nw", + "nextUrl": "https://api.affinity.co/v2/notes/1/attached-opportunities?cursor=ICAgICAgIGFmdGVyOjo6NA" } } }, - "person-list-2": { - "description": "Example response on a Person list.", + "user-reply-2": { + "x-stability-level": "beta", "value": { "data": [ { - "id": "affinity-data-current-job-title", - "name": "Current Job Title", - "type": "enriched", - "valueType": "filterable-text", - "enrichmentSource": "affinity-data" - }, - { - "id": "affinity-data-current-organization", - "name": "Current Organization", - "type": "enriched", - "valueType": "company", - "enrichmentSource": "affinity-data" - }, - { - "id": "affinity-data-industry", - "name": "Industry", - "type": "enriched", - "valueType": "filterable-text-multi", - "enrichmentSource": "affinity-data" - }, - { - "id": "affinity-data-job-titles", - "name": "Job Titles", - "type": "enriched", - "valueType": "filterable-text-multi", - "enrichmentSource": "affinity-data" - }, - { - "id": "affinity-data-location", - "name": "Location", - "type": "enriched", - "valueType": "location", - "enrichmentSource": "affinity-data" - }, - { - "id": "affinity-data-linkedin-url", - "name": "LinkedIn URL", - "type": "enriched", - "valueType": "text", - "enrichmentSource": "affinity-data" - }, - { - "id": "affinity-data-phone-number", - "name": "Phone Number", - "type": "enriched", - "valueType": "filterable-text-multi", - "enrichmentSource": "affinity-data" - }, - { - "id": "companies", - "name": "Organizations", - "type": "list", - "valueType": "company-multi", - "enrichmentSource": null - }, - { - "id": "field-1", - "name": "Custom global field", - "type": "global", - "valueType": "text", - "enrichmentSource": null - }, - { - "id": "field-2", - "name": "Custom list field", - "type": "list", - "valueType": "text", - "enrichmentSource": null - }, - { - "id": "first-chat-message", - "name": "First Chat Message", - "type": "relationship-intelligence", - "valueType": "interaction", - "enrichmentSource": null - }, - { - "id": "first-email", - "name": "First Email", - "type": "relationship-intelligence", - "valueType": "interaction", - "enrichmentSource": null - }, - { - "id": "first-event", - "name": "First Event", - "type": "relationship-intelligence", - "valueType": "interaction", - "enrichmentSource": null - }, - { - "id": "last-chat-message", - "name": "Last Chat Message", - "type": "relationship-intelligence", - "valueType": "interaction", - "enrichmentSource": null - }, - { - "id": "last-contact", - "name": "Last Contact", - "type": "relationship-intelligence", - "valueType": "interaction", - "enrichmentSource": null - }, - { - "id": "last-email", - "name": "Last Email", - "type": "relationship-intelligence", - "valueType": "interaction", - "enrichmentSource": null - }, - { - "id": "last-event", - "name": "Last Event", - "type": "relationship-intelligence", - "valueType": "interaction", - "enrichmentSource": null - }, - { - "id": "next-event", - "name": "Next Event", - "type": "relationship-intelligence", - "valueType": "interaction", - "enrichmentSource": null - }, + "id": 2, + "type": "user-reply", + "content": { + "html": "

This is a user reply note. John Doe was mentioned.

" + }, + "creator": { + "id": 1, + "firstName": "Jane", + "lastName": "Doe", + "primaryEmailAddress": "jane.doe@acme.co", + "type": "internal" + }, + "mentions": [ + { + "id": 1, + "type": "person", + "person": { + "id": 1, + "firstName": "John", + "lastName": "Doe", + "primaryEmailAddress": "john.doe@acme.co", + "type": "internal" + } + } + ], + "parent": { + "id": 1 + }, + "createdAt": "2023-01-01T00:00:00Z", + "updatedAt": "2023-02-01T00:00:00Z" + } + ], + "pagination": { + "prevUrl": "https://api.affinity.co/v2/notes/1/replies?cursor=ICAgICAgYmVmb3JlOjo6Nw", + "nextUrl": "https://api.affinity.co/v2/notes/1/notes?cursor=ICAgICAgIGFmdGVyOjo6NA" + } + } + }, + "ai-notetaker-reply-2": { + "x-stability-level": "beta", + "value": { + "data": [ { - "id": "source-of-introduction", - "name": "Source of Introduction", - "type": "relationship-intelligence", - "valueType": "person", - "enrichmentSource": null + "id": 2, + "type": "ai-notetaker-reply", + "content": { + "html": "

This is an AI Notetaker reply note. John Doe was mentioned.

" + }, + "creator": { + "id": 1, + "firstName": "Jane", + "lastName": "Doe", + "primaryEmailAddress": "jane.doe@acme.co", + "type": "internal" + }, + "mentions": [ + { + "id": 1, + "type": "person", + "person": { + "id": 1, + "firstName": "John", + "lastName": "Doe", + "primaryEmailAddress": "john.doe@acme.co", + "type": "internal" + } + } + ], + "parent": { + "id": 1 + }, + "createdAt": "2023-01-01T00:00:00Z", + "updatedAt": "2023-02-01T00:00:00Z" } ], "pagination": { - "prevUrl": "https://api.affinity.co/v2/lists/2/fields?cursor=ICAgICAgYmVmb3JlOjo6Nw", - "nextUrl": "https://api.affinity.co/v2/lists/2/fields?cursor=ICAgICAgIGFmdGVyOjo6NA" + "prevUrl": "https://api.affinity.co/v2/notes/1/replies?cursor=ICAgICAgYmVmb3JlOjo6Nw", + "nextUrl": "https://api.affinity.co/v2/notes/1/notes?cursor=ICAgICAgIGFmdGVyOjo6NA" } } }, - "opportunity-list-2": { - "description": "Example response on an Opportunity list.", + "entities-3": { + "x-stability-level": "beta", "value": { "data": [ { - "id": "companies", - "name": "Organizations", - "type": "list", - "valueType": "company-multi", - "enrichmentSource": null - }, - { - "id": "field-2", - "name": "Custom list field", - "type": "list", - "valueType": "text", - "enrichmentSource": null - }, - { - "id": "first-chat-message", - "name": "First Chat Message", - "type": "relationship-intelligence", - "valueType": "interaction", - "enrichmentSource": null - }, + "id": 1, + "type": "entities", + "content": { + "html": "

test

%

" + }, + "creator": { + "id": 1, + "firstName": "Jane", + "lastName": "Doe", + "primaryEmailAddress": "jane.doe@acme.co", + "type": "internal" + }, + "mentions": [ + { + "id": 1, + "type": "person", + "person": { + "id": 1, + "firstName": "Jane", + "lastName": "Doe", + "primaryEmailAddress": "jane.doe@acme.co", + "type": "internal" + } + } + ], + "createdAt": "2023-01-01T00:00:00Z", + "updatedAt": "2023-01-01T00:00:00Z", + "permissions": { + "sharingType": "private", + "owner": { + "id": 1, + "firstName": "Jane", + "lastName": "Doe", + "primaryEmailAddress": "jane.doe@acme.co", + "type": "internal" + } + } + } + ], + "pagination": { + "prevUrl": "https://api.affinity.co/v2/persons/1/notes?cursor=ICAgICAgYmVmb3JlOjo6Nw", + "nextUrl": "https://api.affinity.co/v2/persons/1/notes?cursor=ICAgICAgIGFmdGVyOjo6NA" + } + } + }, + "interaction-4": { + "x-stability-level": "beta", + "value": { + "data": [ { - "id": "first-email", - "name": "First Email", - "type": "relationship-intelligence", - "valueType": "interaction", - "enrichmentSource": null - }, + "id": 1, + "type": "interaction", + "content": { + "html": "

test

%

" + }, + "creator": { + "id": 1, + "firstName": "Jane", + "lastName": "Doe", + "primaryEmailAddress": "jane.doe@acme.co", + "type": "internal" + }, + "mentions": [ + { + "id": 1, + "type": "person", + "person": { + "id": 1, + "firstName": "Jane", + "lastName": "Doe", + "primaryEmailAddress": "jane.doe@acme.co", + "type": "internal" + } + } + ], + "createdAt": "2023-01-01T00:00:00Z", + "updatedAt": "2023-01-01T00:00:00Z", + "permissions": { + "sharingType": "private", + "owner": { + "id": 1, + "firstName": "Jane", + "lastName": "Doe", + "primaryEmailAddress": "jane.doe@acme.co", + "type": "internal" + } + }, + "interaction": { + "id": 2, + "type": "call" + } + } + ], + "pagination": { + "prevUrl": "https://api.affinity.co/v2/persons/1/notes?cursor=ICAgICAgYmVmb3JlOjo6Nw", + "nextUrl": "https://api.affinity.co/v2/persons/1/notes?cursor=ICAgICAgIGFmdGVyOjo6NA" + } + } + }, + "ai-notetaker-3": { + "x-stability-level": "beta", + "value": { + "data": [ { - "id": "first-event", - "name": "First Event", - "type": "relationship-intelligence", - "valueType": "interaction", - "enrichmentSource": null - }, + "id": 1, + "type": "ai-notetaker", + "content": { + "html": "

test

%

" + }, + "creator": { + "id": 1, + "firstName": "Jane", + "lastName": "Doe", + "primaryEmailAddress": "jane.doe@acme.co", + "type": "internal" + }, + "mentions": [ + { + "id": 1, + "type": "person", + "person": { + "id": 1, + "firstName": "Jane", + "lastName": "Doe", + "primaryEmailAddress": "jane.doe@acme.co", + "type": "internal" + } + } + ], + "createdAt": "2023-01-01T00:00:00Z", + "updatedAt": "2023-01-01T00:00:00Z", + "permissions": { + "sharingType": "private", + "owner": { + "id": 1, + "firstName": "Jane", + "lastName": "Doe", + "primaryEmailAddress": "jane.doe@acme.co", + "type": "internal" + } + } + } + ], + "pagination": { + "prevUrl": "https://api.affinity.co/v2/persons/1/notes?cursor=ICAgICAgYmVmb3JlOjo6Nw", + "nextUrl": "https://api.affinity.co/v2/persons/1/notes?cursor=ICAgICAgIGFmdGVyOjo6NA" + } + } + }, + "merges-list-2": { + "x-stability-level": "beta", + "summary": "Person merges", + "description": "Example response showing multiple person merges with different statuses", + "value": { + "data": [ { - "id": "last-chat-message", - "name": "Last Chat Message", - "type": "relationship-intelligence", - "valueType": "interaction", - "enrichmentSource": null + "id": 12, + "status": "success", + "taskId": "789e0123-e45b-67c8-d901-234567890123", + "startedAt": "2025-06-03T10:30:00Z", + "primaryPersonId": 12345, + "duplicatePersonId": 67890, + "completedAt": "2025-06-03T10:32:15Z", + "errorMessage": null }, { - "id": "last-contact", - "name": "Last Contact", - "type": "relationship-intelligence", - "valueType": "interaction", - "enrichmentSource": null - }, + "id": 13, + "status": "failed", + "taskId": "456e7890-1234-5678-9012-345678901234", + "startedAt": "2025-06-03T09:15:00Z", + "primaryPersonId": 54321, + "duplicatePersonId": 98765, + "completedAt": "2025-06-03T09:16:30Z", + "errorMessage": "Primary person not found" + } + ], + "pagination": { + "nextUrl": "https://api.affinity.co/v2/persons/merge?cursor=eyJpZCI6NDU2ZTc4OTAtZTEyYi0zNGM1LWQ2NzgtOTAxMjM0NTY3ODkwfQ==", + "prevUrl": null + } + } + }, + "merge-persons": { + "x-stability-level": "beta", + "summary": "Merge two person profiles", + "description": "Example request to merge a duplicate person profile into a primary person profile. The primary person (ID 12345) will be kept and all data from the duplicate person (ID 67890) will be merged into it.", + "value": { + "primaryPersonId": 12345, + "duplicatePersonId": 67890 + } + }, + "merge-initiated-2": { + "x-stability-level": "beta", + "summary": "Merge task initiated", + "description": "Response when a person merge task has been accepted for processing. The task ID can be used to track the progress of the merge task.", + "value": { + "taskUrl": "https://api.affinity.co/v2/tasks/person-merges/123e4567-e89b-12d3-a456-426614174000" + } + }, + "succeeded-merge-2": { + "x-stability-level": "beta", + "summary": "Succeeded person merge", + "description": "Example of a successful person merge", + "value": { + "id": 12345, + "status": "success", + "taskId": "1b9684ad-e954-46d7-9684-ade95436d7dd", + "startedAt": "2025-06-03T10:30:00Z", + "primaryPersonId": 12345, + "duplicatePersonId": 67890, + "completedAt": "2025-06-03T10:32:15Z", + "errorMessage": null + } + }, + "failed-merge-2": { + "x-stability-level": "beta", + "summary": "Failed person merge", + "description": "Example of a failed person merge with error details", + "value": { + "id": 67890, + "status": "failed", + "taskId": "789e0123-e45b-67c8-d901-234567890123", + "startedAt": "2025-06-03T09:15:00Z", + "primaryPersonId": 54321, + "duplicatePersonId": 98765, + "completedAt": "2025-06-03T09:16:30Z", + "errorMessage": "Primary person not found" + } + }, + "in-progress-merge-2": { + "x-stability-level": "beta", + "summary": "In-progress person merge", + "description": "Example of a person merge currently being processed", + "value": { + "id": 98765, + "status": "in-progress", + "taskId": "456e7890-e12b-34c5-d678-901234567890", + "startedAt": "2025-06-03T11:45:00Z", + "primaryPersonId": 24680, + "duplicatePersonId": 13579, + "completedAt": null, + "errorMessage": null + } + }, + "tasks-list": { + "x-stability-level": "beta", + "summary": "List of company merge tasks", + "description": "Example response showing multiple company merge tasks with different statuses", + "value": { + "data": [ { - "id": "last-email", - "name": "Last Email", - "type": "relationship-intelligence", - "valueType": "interaction", - "enrichmentSource": null + "id": "123e4567-e89b-12d3-a456-426614174000", + "status": "success", + "resultsSummary": { + "total": 1, + "inProgress": 0, + "success": 1, + "failed": 0 + } }, { - "id": "last-event", - "name": "Last Event", - "type": "relationship-intelligence", - "valueType": "interaction", - "enrichmentSource": null - }, + "id": "456e7890-e12b-34c5-d678-901234567890", + "status": "failed", + "resultsSummary": { + "total": 1, + "inProgress": 0, + "success": 0, + "failed": 1 + } + } + ], + "pagination": { + "nextUrl": "https://api.affinity.co/v2/tasks/company-merges?cursor=eyJpZCI6NDU2ZTc4OTAtZTEyYi0zNGM1LWQ2NzgtOTAxMjM0NTY3ODkwfQ==", + "prevUrl": null + } + } + }, + "task-in-progress": { + "x-stability-level": "beta", + "summary": "Merge task in progress", + "description": "Example response showing a merge task that is currently being processed.", + "value": { + "id": "456e7890-e12b-34c5-d678-901234567890", + "status": "in-progress", + "resultsSummary": { + "total": 1, + "inProgress": 1, + "success": 0, + "failed": 0 + } + } + }, + "task-success": { + "x-stability-level": "beta", + "summary": "Merge task succeeded", + "description": "Example response showing a merge task that has been successfully completed.", + "value": { + "id": "d8ff68ec-33d9-4d70-bf68-ec33d93d7092", + "status": "success", + "resultsSummary": { + "total": 1, + "inProgress": 0, + "success": 1, + "failed": 0 + } + } + }, + "task-failed": { + "x-stability-level": "beta", + "summary": "Merge task failed", + "description": "Example response showing a merge task that failed during processing.", + "value": { + "id": "012e3456-a78b-90c1-d234-567890123456", + "status": "failed", + "resultsSummary": { + "total": 1, + "inProgress": 0, + "success": 0, + "failed": 1 + } + } + }, + "tasks-list-2": { + "x-stability-level": "beta", + "summary": "Person merge tasks", + "description": "Example response showing multiple person merge tasks with different statuses", + "value": { + "data": [ { - "id": "next-event", - "name": "Next Event", - "type": "relationship-intelligence", - "valueType": "interaction", - "enrichmentSource": null + "id": "123e4567-e89b-12d3-a456-426614174000", + "status": "success", + "resultsSummary": { + "total": 1, + "inProgress": 0, + "success": 1, + "failed": 0 + } }, { - "id": "persons", - "name": "People", - "type": "list", - "valueType": "person-multi", - "enrichmentSource": null + "id": "456e7890-e12b-34c5-d678-901234567890", + "status": "failed", + "resultsSummary": { + "total": 1, + "inProgress": 0, + "success": 0, + "failed": 1 + } } ], "pagination": { - "prevUrl": "https://api.affinity.co/v2/lists/3/fields?cursor=ICAgICAgYmVmb3JlOjo6Nw", - "nextUrl": "https://api.affinity.co/v2/lists/3/fields?cursor=ICAgICAgIGFmdGVyOjo6NA" + "nextUrl": "https://api.affinity.co/v2/tasks/person-merges?cursor=eyJpZCI6NDU2ZTc4OTAtZTEyYi0zNGM1LWQ2NzgtOTAxMjM0NTY3ODkwfQ==", + "prevUrl": null + } + } + }, + "task-success-2": { + "x-stability-level": "beta", + "summary": "Merge task succeeded", + "description": "Example response showing a merge task that has been successfully completed.", + "value": { + "id": "76b45575-c17a-4b73-b455-75c17a9b737c", + "status": "success", + "resultsSummary": { + "total": 1, + "inProgress": 0, + "success": 1, + "failed": 0 } } } + }, + "parameters": { + "notes.includes": { + "x-stability-level": "beta", + "name": "includes", + "description": "Additional properties to include in the response", + "in": "query", + "required": false, + "style": "form", + "explode": true, + "schema": { + "title": "notes.includes", + "type": "array", + "items": { + "type": "string", + "enum": [ + "companiesPreview", + "personsPreview", + "opportunitiesPreview", + "repliesCount" + ] + }, + "uniqueItems": true + } + }, + "note.includes": { + "x-stability-level": "beta", + "name": "includes", + "description": "Additional properties to include in the response", + "in": "query", + "required": false, + "style": "form", + "explode": true, + "schema": { + "title": "note.includes", + "type": "array", + "items": { + "type": "string", + "enum": [ + "companiesPreview", + "personsPreview", + "opportunitiesPreview", + "repliesCount" + ] + }, + "uniqueItems": true + } + } } } -} +} \ No newline at end of file diff --git a/openapitools.json b/openapitools.json index 3643a08..72066ef 100644 --- a/openapitools.json +++ b/openapitools.json @@ -2,7 +2,7 @@ "$schema": "./node_modules/@openapitools/openapi-generator-cli/config.schema.json", "spaces": 2, "generator-cli": { - "version": "7.12.0", + "version": "7.17.0", "generators": { "v2": { "generatorName": "typescript", diff --git a/src/v2/generated/.openapi-generator/FILES b/src/v2/generated/.openapi-generator/FILES index 87f5879..8b4df85 100644 --- a/src/v2/generated/.openapi-generator/FILES +++ b/src/v2/generated/.openapi-generator/FILES @@ -1,26 +1,41 @@ .gitattributes .gitignore .openapi-generator-ignore -AuthApi.md -CompaniesApi.md -ListsApi.md -OpportunitiesApi.md -PersonsApi.md apis/AuthApi.ts +apis/CallsApi.ts +apis/ChatMessagesApi.ts apis/CompaniesApi.ts +apis/CompanyMergesApi.ts +apis/EmailsApi.ts apis/ListsApi.ts +apis/MeetingsApi.ts +apis/NotesApi.ts apis/OpportunitiesApi.ts +apis/PersonMergesApi.ts apis/PersonsApi.ts apis/baseapi.ts apis/exception.ts auth/auth.ts configuration.ts +docs/AuthApi.md +docs/CallsApi.md +docs/ChatMessagesApi.md +docs/CompaniesApi.md +docs/CompanyMergesApi.md +docs/EmailsApi.md +docs/ListsApi.md +docs/MeetingsApi.md +docs/NotesApi.md +docs/OpportunitiesApi.md +docs/PersonMergesApi.md +docs/PersonsApi.md git_push.sh http/http.ts http/isomorphic-fetch.ts index.ts middleware.ts models/Attendee.ts +models/AttendeesPreview.ts models/AuthenticationError.ts models/AuthorizationError.ts models/AuthorizationErrors.ts @@ -30,7 +45,15 @@ models/CompaniesValue.ts models/CompaniesValueUpdate.ts models/Company.ts models/CompanyData.ts +models/CompanyDataPaged.ts models/CompanyListEntry.ts +models/CompanyMergeRequest.ts +models/CompanyMergeResponse.ts +models/CompanyMergeState.ts +models/CompanyMergeStatePaged.ts +models/CompanyMergeTask.ts +models/CompanyMergeTaskPaged.ts +models/CompanyMergeTaskResultsSummary.ts models/CompanyPaged.ts models/CompanyReference.ts models/CompanyValue.ts @@ -57,10 +80,16 @@ models/FloatsValue.ts models/FormulaNumber.ts models/FormulaValue.ts models/Grant.ts -models/InlineObject.ts -models/InlineObjectErrorsInner.ts models/Interaction.ts models/InteractionValue.ts +models/InteractionsCall.ts +models/InteractionsCallPaged.ts +models/InteractionsChatMessage.ts +models/InteractionsChatMessagePaged.ts +models/InteractionsEmail.ts +models/InteractionsEmailPaged.ts +models/InteractionsMeeting.ts +models/InteractionsMeetingPaged.ts models/List.ts models/ListEntry.ts models/ListEntryBatchOperationResponse.ts @@ -83,15 +112,48 @@ models/NotAcceptableError.ts models/NotFoundError.ts models/NotFoundErrors.ts models/NotImplementedError.ts +models/NotesAiNotetakerReplyNote.ts +models/NotesAiNotetakerRootNote.ts +models/NotesBaseNote.ts +models/NotesBaseReply.ts +models/NotesBaseReplyParent.ts +models/NotesBaseRootNote.ts +models/NotesCallInteraction.ts +models/NotesChatMessageInteraction.ts +models/NotesCompaniesPreview.ts +models/NotesContent.ts +models/NotesEmailInteraction.ts +models/NotesEntitiesNote.ts +models/NotesInteraction.ts +models/NotesInteractionNote.ts +models/NotesMeetingInteraction.ts +models/NotesNote.ts +models/NotesNotesPaged.ts +models/NotesOpportunitiesPreview.ts +models/NotesPermissionSettings.ts +models/NotesPersonMention.ts +models/NotesPersonsPreview.ts +models/NotesRepliesPaged.ts +models/NotesReply.ts +models/NotesUserReplyNote.ts models/ObjectSerializer.ts models/Opportunity.ts models/OpportunityListEntry.ts models/OpportunityPaged.ts models/OpportunityWithFields.ts models/Pagination.ts +models/PaginationWithTotalCount.ts models/Person.ts models/PersonData.ts +models/PersonDataPaged.ts +models/PersonDataPreview.ts models/PersonListEntry.ts +models/PersonMergeRequest.ts +models/PersonMergeResponse.ts +models/PersonMergeState.ts +models/PersonMergeStatePaged.ts +models/PersonMergeTask.ts +models/PersonMergeTaskPaged.ts models/PersonPaged.ts models/PersonReference.ts models/PersonValue.ts @@ -104,6 +166,8 @@ models/RankedDropdownReference.ts models/RankedDropdownValue.ts models/RankedDropdownValueUpdate.ts models/RateLimitError.ts +models/Responses400.ts +models/Responses400ErrorsInner.ts models/SavedView.ts models/SavedViewPaged.ts models/ServerError.ts diff --git a/src/v2/generated/.openapi-generator/VERSION b/src/v2/generated/.openapi-generator/VERSION index 5f84a81..6328c54 100644 --- a/src/v2/generated/.openapi-generator/VERSION +++ b/src/v2/generated/.openapi-generator/VERSION @@ -1 +1 @@ -7.12.0 +7.17.0 diff --git a/src/v2/generated/AuthApi.md b/src/v2/generated/AuthApi.md deleted file mode 100644 index feac428..0000000 --- a/src/v2/generated/AuthApi.md +++ /dev/null @@ -1,58 +0,0 @@ -# Affinity.AuthApi - -All URIs are relative to *https://api.affinity.co* - -Method | HTTP request | Description -------------- | ------------- | ------------- -[**getV2AuthWhoami**](AuthApi.md#getV2AuthWhoami) | **GET** /v2/auth/whoami | Get current user - - -# **getV2AuthWhoami** -> WhoAmI getV2AuthWhoami() - -Returns metadata about the current user. - -### Example - - -```typescript -import { createConfiguration, AuthApi } from '@planet-a/affinity-node/v2'; - -const configuration = createConfiguration(); -const apiInstance = new AuthApi(configuration); - -const request = {}; - -const data = await apiInstance.getV2AuthWhoami(request); -console.log('API called successfully. Returned data:', data); -``` - - -### Parameters -This endpoint does not need any parameter. - - -### Return type - -**WhoAmI** - -### Authorization - -[bearerAuth](README.md#bearerAuth) - -### HTTP request headers - - - **Content-Type**: Not defined - - **Accept**: application/json - - -### HTTP response details -| Status code | Description | Response headers | -|-------------|-------------|------------------| -**200** | Get current user | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**404** | Not Found | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**0** | Errors | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| - -[[Back to top]](#) [[Back to API list]](README.md#documentation-for-api-endpoints) [[Back to Model list]](README.md#documentation-for-models) [[Back to README]](README.md) - - diff --git a/src/v2/generated/CompaniesApi.md b/src/v2/generated/CompaniesApi.md deleted file mode 100644 index 749487c..0000000 --- a/src/v2/generated/CompaniesApi.md +++ /dev/null @@ -1,338 +0,0 @@ -# Affinity.CompaniesApi - -All URIs are relative to *https://api.affinity.co* - -Method | HTTP request | Description -------------- | ------------- | ------------- -[**getV2Companies**](CompaniesApi.md#getV2Companies) | **GET** /v2/companies | Get all Companies -[**getV2CompaniesFields**](CompaniesApi.md#getV2CompaniesFields) | **GET** /v2/companies/fields | Get metadata on Company Fields -[**getV2CompaniesId**](CompaniesApi.md#getV2CompaniesId) | **GET** /v2/companies/{id} | Get a single Company -[**getV2CompaniesIdListEntries**](CompaniesApi.md#getV2CompaniesIdListEntries) | **GET** /v2/companies/{id}/list-entries | Get a Company\'s List Entries -[**getV2CompaniesIdLists**](CompaniesApi.md#getV2CompaniesIdLists) | **GET** /v2/companies/{id}/lists | Get a Company\'s Lists - - -# **getV2Companies** -> CompanyPaged getV2Companies() - -Paginate through Companies in Affinity. Returns basic information and non-list-specific field data on each Company. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/companies/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Companies will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All Organizations directory\" [permission](#section/Getting-Started/Permissions). - -### Example - - -```typescript -import { createConfiguration, CompaniesApi } from '@planet-a/affinity-node/v2'; -import type { CompaniesApiGetV2CompaniesRequest } from '@planet-a/affinity-node/v2'; - -const configuration = createConfiguration(); -const apiInstance = new CompaniesApi(configuration); - -const request: CompaniesApiGetV2CompaniesRequest = { - // Cursor for the next or previous page (optional) - cursor: "cursor_example", - // Number of items to include in the page (optional) - limit: 100, - // Company IDs (optional) - ids: [ - 1, - ], - // Field IDs for which to return field data (optional) - fieldIds: [ - "fieldIds_example", - ], - // Field Types for which to return field data (optional) - fieldTypes: [ - "enriched", - ], -}; - -const data = await apiInstance.getV2Companies(request); -console.log('API called successfully. Returned data:', data); -``` - - -### Parameters - -Name | Type | Description | Notes -------------- | ------------- | ------------- | ------------- - **cursor** | [**string**] | Cursor for the next or previous page | (optional) defaults to undefined - **limit** | [**number**] | Number of items to include in the page | (optional) defaults to 100 - **ids** | **Array<number>** | Company IDs | (optional) defaults to undefined - **fieldIds** | **Array<string>** | Field IDs for which to return field data | (optional) defaults to undefined - **fieldTypes** | **Array<'enriched' | 'global' | 'relationship-intelligence'>** | Field Types for which to return field data | (optional) defaults to undefined - - -### Return type - -**CompanyPaged** - -### Authorization - -[bearerAuth](README.md#bearerAuth) - -### HTTP request headers - - - **Content-Type**: Not defined - - **Accept**: application/json - - -### HTTP response details -| Status code | Description | Response headers | -|-------------|-------------|------------------| -**200** | Get all Companies | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**400** | Bad Request | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**403** | Forbidden | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**0** | Errors | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| - -[[Back to top]](#) [[Back to API list]](README.md#documentation-for-api-endpoints) [[Back to Model list]](README.md#documentation-for-models) [[Back to README]](README.md) - -# **getV2CompaniesFields** -> FieldMetadataPaged getV2CompaniesFields() - -Returns metadata on non-list-specific Company Fields. Use the returned Field IDs to request field data from the GET `/v2/companies` and GET `/v2/companies/{id}` endpoints. - -### Example - - -```typescript -import { createConfiguration, CompaniesApi } from '@planet-a/affinity-node/v2'; -import type { CompaniesApiGetV2CompaniesFieldsRequest } from '@planet-a/affinity-node/v2'; - -const configuration = createConfiguration(); -const apiInstance = new CompaniesApi(configuration); - -const request: CompaniesApiGetV2CompaniesFieldsRequest = { - // Cursor for the next or previous page (optional) - cursor: "cursor_example", - // Number of items to include in the page (optional) - limit: 100, -}; - -const data = await apiInstance.getV2CompaniesFields(request); -console.log('API called successfully. Returned data:', data); -``` - - -### Parameters - -Name | Type | Description | Notes -------------- | ------------- | ------------- | ------------- - **cursor** | [**string**] | Cursor for the next or previous page | (optional) defaults to undefined - **limit** | [**number**] | Number of items to include in the page | (optional) defaults to 100 - - -### Return type - -**FieldMetadataPaged** - -### Authorization - -[bearerAuth](README.md#bearerAuth) - -### HTTP request headers - - - **Content-Type**: Not defined - - **Accept**: application/json - - -### HTTP response details -| Status code | Description | Response headers | -|-------------|-------------|------------------| -**200** | Get metadata on Company Fields | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**400** | Bad Request | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**0** | Errors | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| - -[[Back to top]](#) [[Back to API list]](README.md#documentation-for-api-endpoints) [[Back to Model list]](README.md#documentation-for-models) [[Back to README]](README.md) - -# **getV2CompaniesId** -> Company getV2CompaniesId() - -Returns basic information and non-list-specific field data on the requested Company. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/companies/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Companies will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All Organizations directory\" [permission](#section/Getting-Started/Permissions). - -### Example - - -```typescript -import { createConfiguration, CompaniesApi } from '@planet-a/affinity-node/v2'; -import type { CompaniesApiGetV2CompaniesIdRequest } from '@planet-a/affinity-node/v2'; - -const configuration = createConfiguration(); -const apiInstance = new CompaniesApi(configuration); - -const request: CompaniesApiGetV2CompaniesIdRequest = { - // Company ID - id: 1, - // Field IDs for which to return field data (optional) - fieldIds: [ - "fieldIds_example", - ], - // Field Types for which to return field data (optional) - fieldTypes: [ - "enriched", - ], -}; - -const data = await apiInstance.getV2CompaniesId(request); -console.log('API called successfully. Returned data:', data); -``` - - -### Parameters - -Name | Type | Description | Notes -------------- | ------------- | ------------- | ------------- - **id** | [**number**] | Company ID | defaults to undefined - **fieldIds** | **Array<string>** | Field IDs for which to return field data | (optional) defaults to undefined - **fieldTypes** | **Array<'enriched' | 'global' | 'relationship-intelligence'>** | Field Types for which to return field data | (optional) defaults to undefined - - -### Return type - -**Company** - -### Authorization - -[bearerAuth](README.md#bearerAuth) - -### HTTP request headers - - - **Content-Type**: Not defined - - **Accept**: application/json - - -### HTTP response details -| Status code | Description | Response headers | -|-------------|-------------|------------------| -**200** | Get a single Company | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**400** | Bad Request | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**403** | Forbidden | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**404** | Not Found | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**0** | Errors | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| - -[[Back to top]](#) [[Back to API list]](README.md#documentation-for-api-endpoints) [[Back to Model list]](README.md#documentation-for-models) [[Back to README]](README.md) - -# **getV2CompaniesIdListEntries** -> ListEntryPaged getV2CompaniesIdListEntries() - -Paginate through the List Entries (AKA rows) for the given Company across all Lists. Each List Entry includes field data for the Company, including list-specific field data. Each List Entry also includes metadata about its creation, i.e., when it was added to the List and by whom. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - -### Example - - -```typescript -import { createConfiguration, CompaniesApi } from '@planet-a/affinity-node/v2'; -import type { CompaniesApiGetV2CompaniesIdListEntriesRequest } from '@planet-a/affinity-node/v2'; - -const configuration = createConfiguration(); -const apiInstance = new CompaniesApi(configuration); - -const request: CompaniesApiGetV2CompaniesIdListEntriesRequest = { - // Company ID - id: 1, - // Cursor for the next or previous page (optional) - cursor: "cursor_example", - // Number of items to include in the page (optional) - limit: 100, -}; - -const data = await apiInstance.getV2CompaniesIdListEntries(request); -console.log('API called successfully. Returned data:', data); -``` - - -### Parameters - -Name | Type | Description | Notes -------------- | ------------- | ------------- | ------------- - **id** | [**number**] | Company ID | defaults to undefined - **cursor** | [**string**] | Cursor for the next or previous page | (optional) defaults to undefined - **limit** | [**number**] | Number of items to include in the page | (optional) defaults to 100 - - -### Return type - -**ListEntryPaged** - -### Authorization - -[bearerAuth](README.md#bearerAuth) - -### HTTP request headers - - - **Content-Type**: Not defined - - **Accept**: application/json - - -### HTTP response details -| Status code | Description | Response headers | -|-------------|-------------|------------------| -**200** | Get a Company\'s List Entries | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**400** | Bad Request | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**403** | Forbidden | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**404** | Not Found | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**0** | Errors | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| - -[[Back to top]](#) [[Back to API list]](README.md#documentation-for-api-endpoints) [[Back to Model list]](README.md#documentation-for-models) [[Back to README]](README.md) - -# **getV2CompaniesIdLists** -> ListPaged getV2CompaniesIdLists() - -Returns metadata for all the Lists on which the given Company appears. - -### Example - - -```typescript -import { createConfiguration, CompaniesApi } from '@planet-a/affinity-node/v2'; -import type { CompaniesApiGetV2CompaniesIdListsRequest } from '@planet-a/affinity-node/v2'; - -const configuration = createConfiguration(); -const apiInstance = new CompaniesApi(configuration); - -const request: CompaniesApiGetV2CompaniesIdListsRequest = { - // Company ID - id: 1, - // Cursor for the next or previous page (optional) - cursor: "cursor_example", - // Number of items to include in the page (optional) - limit: 100, -}; - -const data = await apiInstance.getV2CompaniesIdLists(request); -console.log('API called successfully. Returned data:', data); -``` - - -### Parameters - -Name | Type | Description | Notes -------------- | ------------- | ------------- | ------------- - **id** | [**number**] | Company ID | defaults to undefined - **cursor** | [**string**] | Cursor for the next or previous page | (optional) defaults to undefined - **limit** | [**number**] | Number of items to include in the page | (optional) defaults to 100 - - -### Return type - -**ListPaged** - -### Authorization - -[bearerAuth](README.md#bearerAuth) - -### HTTP request headers - - - **Content-Type**: Not defined - - **Accept**: application/json - - -### HTTP response details -| Status code | Description | Response headers | -|-------------|-------------|------------------| -**200** | Get a Company\'s Lists | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**400** | Bad Request | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**404** | Not Found | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**0** | Errors | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| - -[[Back to top]](#) [[Back to API list]](README.md#documentation-for-api-endpoints) [[Back to Model list]](README.md#documentation-for-models) [[Back to README]](README.md) - - diff --git a/src/v2/generated/ListsApi.md b/src/v2/generated/ListsApi.md deleted file mode 100644 index 7921352..0000000 --- a/src/v2/generated/ListsApi.md +++ /dev/null @@ -1,805 +0,0 @@ -# Affinity.ListsApi - -All URIs are relative to *https://api.affinity.co* - -Method | HTTP request | Description -------------- | ------------- | ------------- -[**getV2ListsListidSavedViews**](ListsApi.md#getV2ListsListidSavedViews) | **GET** /v2/lists/{listId}/saved-views | Get metadata on Saved Views -[**getV2ListsListidSavedViewsViewid**](ListsApi.md#getV2ListsListidSavedViewsViewid) | **GET** /v2/lists/{listId}/saved-views/{viewId} | Get metadata on a single Saved View -[**getV2ListsListidSavedViewsViewidListEntries**](ListsApi.md#getV2ListsListidSavedViewsViewidListEntries) | **GET** /v2/lists/{listId}/saved-views/{viewId}/list-entries | Get all List Entries on a Saved View -[**v2ListsGET**](ListsApi.md#v2ListsGET) | **GET** /v2/lists | Get metadata on all Lists -[**v2ListsListIdFieldsGET**](ListsApi.md#v2ListsListIdFieldsGET) | **GET** /v2/lists/{listId}/fields | Get metadata on a single List\'s Fields -[**v2ListsListIdGET**](ListsApi.md#v2ListsListIdGET) | **GET** /v2/lists/{listId} | Get metadata on a single List -[**v2ListsListIdListEntriesGET**](ListsApi.md#v2ListsListIdListEntriesGET) | **GET** /v2/lists/{listId}/list-entries | Get all List Entries on a List -[**v2ListsListIdListEntriesListEntryIdFieldsFieldIdGET**](ListsApi.md#v2ListsListIdListEntriesListEntryIdFieldsFieldIdGET) | **GET** /v2/lists/{listId}/list-entries/{listEntryId}/fields/{fieldId} | Get a single field value [BETA] -[**v2ListsListIdListEntriesListEntryIdFieldsFieldIdPOST**](ListsApi.md#v2ListsListIdListEntriesListEntryIdFieldsFieldIdPOST) | **POST** /v2/lists/{listId}/list-entries/{listEntryId}/fields/{fieldId} | Update a single field value on a List Entry [BETA] -[**v2ListsListIdListEntriesListEntryIdFieldsGET**](ListsApi.md#v2ListsListIdListEntriesListEntryIdFieldsGET) | **GET** /v2/lists/{listId}/list-entries/{listEntryId}/fields | Get field values on a single List Entry [BETA] -[**v2ListsListIdListEntriesListEntryIdFieldsPATCH**](ListsApi.md#v2ListsListIdListEntriesListEntryIdFieldsPATCH) | **PATCH** /v2/lists/{listId}/list-entries/{listEntryId}/fields | Perform batch operations on a list entry\'s fields [BETA] -[**v2ListsListIdListEntriesListEntryIdGET**](ListsApi.md#v2ListsListIdListEntriesListEntryIdGET) | **GET** /v2/lists/{listId}/list-entries/{listEntryId} | Get a single List Entry on a List [BETA] - - -# **getV2ListsListidSavedViews** -> SavedViewPaged getV2ListsListidSavedViews() - -Returns metadata on the Saved Views on a List. - -### Example - - -```typescript -import { createConfiguration, ListsApi } from '@planet-a/affinity-node/v2'; -import type { ListsApiGetV2ListsListidSavedViewsRequest } from '@planet-a/affinity-node/v2'; - -const configuration = createConfiguration(); -const apiInstance = new ListsApi(configuration); - -const request: ListsApiGetV2ListsListidSavedViewsRequest = { - // List ID - listId: 1, - // Cursor for the next or previous page (optional) - cursor: "cursor_example", - // Number of items to include in the page (optional) - limit: 100, -}; - -const data = await apiInstance.getV2ListsListidSavedViews(request); -console.log('API called successfully. Returned data:', data); -``` - - -### Parameters - -Name | Type | Description | Notes -------------- | ------------- | ------------- | ------------- - **listId** | [**number**] | List ID | defaults to undefined - **cursor** | [**string**] | Cursor for the next or previous page | (optional) defaults to undefined - **limit** | [**number**] | Number of items to include in the page | (optional) defaults to 100 - - -### Return type - -**SavedViewPaged** - -### Authorization - -[bearerAuth](README.md#bearerAuth) - -### HTTP request headers - - - **Content-Type**: Not defined - - **Accept**: application/json - - -### HTTP response details -| Status code | Description | Response headers | -|-------------|-------------|------------------| -**200** | Get metadata on Saved Views | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**400** | Bad Request | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**404** | Not Found | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**0** | Errors | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| - -[[Back to top]](#) [[Back to API list]](README.md#documentation-for-api-endpoints) [[Back to Model list]](README.md#documentation-for-models) [[Back to README]](README.md) - -# **getV2ListsListidSavedViewsViewid** -> SavedView getV2ListsListidSavedViewsViewid() - -Returns metadata on a single Saved View. - -### Example - - -```typescript -import { createConfiguration, ListsApi } from '@planet-a/affinity-node/v2'; -import type { ListsApiGetV2ListsListidSavedViewsViewidRequest } from '@planet-a/affinity-node/v2'; - -const configuration = createConfiguration(); -const apiInstance = new ListsApi(configuration); - -const request: ListsApiGetV2ListsListidSavedViewsViewidRequest = { - // List ID - listId: 1, - // Saved view ID - viewId: 1, -}; - -const data = await apiInstance.getV2ListsListidSavedViewsViewid(request); -console.log('API called successfully. Returned data:', data); -``` - - -### Parameters - -Name | Type | Description | Notes -------------- | ------------- | ------------- | ------------- - **listId** | [**number**] | List ID | defaults to undefined - **viewId** | [**number**] | Saved view ID | defaults to undefined - - -### Return type - -**SavedView** - -### Authorization - -[bearerAuth](README.md#bearerAuth) - -### HTTP request headers - - - **Content-Type**: Not defined - - **Accept**: application/json - - -### HTTP response details -| Status code | Description | Response headers | -|-------------|-------------|------------------| -**200** | Get metadata on a single Saved View | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**400** | Bad Request | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**404** | Not Found | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**0** | Errors | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| - -[[Back to top]](#) [[Back to API list]](README.md#documentation-for-api-endpoints) [[Back to Model list]](README.md#documentation-for-models) [[Back to README]](README.md) - -# **getV2ListsListidSavedViewsViewidListEntries** -> ListEntryWithEntityPaged getV2ListsListidSavedViewsViewidListEntries() - -Paginate through the List Entries (AKA rows) on a given Saved View. Use this endpoint when you need to filter entities or only want **some** field data to be returned: This endpoint respects the filters set on a Saved View via web app, and only returns field data corresponding to the columns that have been pulled into the Saved View via web app. Though this endpoint respects the Saved View\'s filters and column/Field selection, it does not yet preserve sort order. This endpoint also only supports **sheet-type Saved Views**, and not board- or dashboard-type Saved Views. See the [Data Model](#section/Data-Model) section for more information about Saved Views. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - -### Example - - -```typescript -import { createConfiguration, ListsApi } from '@planet-a/affinity-node/v2'; -import type { ListsApiGetV2ListsListidSavedViewsViewidListEntriesRequest } from '@planet-a/affinity-node/v2'; - -const configuration = createConfiguration(); -const apiInstance = new ListsApi(configuration); - -const request: ListsApiGetV2ListsListidSavedViewsViewidListEntriesRequest = { - // List ID - listId: 1, - // Saved view ID - viewId: 1, - // Cursor for the next or previous page (optional) - cursor: "cursor_example", - // Number of items to include in the page (optional) - limit: 100, -}; - -const data = await apiInstance.getV2ListsListidSavedViewsViewidListEntries(request); -console.log('API called successfully. Returned data:', data); -``` - - -### Parameters - -Name | Type | Description | Notes -------------- | ------------- | ------------- | ------------- - **listId** | [**number**] | List ID | defaults to undefined - **viewId** | [**number**] | Saved view ID | defaults to undefined - **cursor** | [**string**] | Cursor for the next or previous page | (optional) defaults to undefined - **limit** | [**number**] | Number of items to include in the page | (optional) defaults to 100 - - -### Return type - -**ListEntryWithEntityPaged** - -### Authorization - -[bearerAuth](README.md#bearerAuth) - -### HTTP request headers - - - **Content-Type**: Not defined - - **Accept**: application/json - - -### HTTP response details -| Status code | Description | Response headers | -|-------------|-------------|------------------| -**200** | Get all List Entries on a Saved View | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**400** | Bad Request | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**403** | Forbidden | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**404** | Not Found | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**0** | Errors | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| - -[[Back to top]](#) [[Back to API list]](README.md#documentation-for-api-endpoints) [[Back to Model list]](README.md#documentation-for-models) [[Back to README]](README.md) - -# **v2ListsGET** -> ListWithTypePaged v2ListsGET() - -Returns metadata on Lists. - -### Example - - -```typescript -import { createConfiguration, ListsApi } from '@planet-a/affinity-node/v2'; -import type { ListsApiV2ListsGETRequest } from '@planet-a/affinity-node/v2'; - -const configuration = createConfiguration(); -const apiInstance = new ListsApi(configuration); - -const request: ListsApiV2ListsGETRequest = { - // Cursor for the next or previous page (optional) - cursor: "cursor_example", - // Number of items to include in the page (optional) - limit: 100, -}; - -const data = await apiInstance.v2ListsGET(request); -console.log('API called successfully. Returned data:', data); -``` - - -### Parameters - -Name | Type | Description | Notes -------------- | ------------- | ------------- | ------------- - **cursor** | [**string**] | Cursor for the next or previous page | (optional) defaults to undefined - **limit** | [**number**] | Number of items to include in the page | (optional) defaults to 100 - - -### Return type - -**ListWithTypePaged** - -### Authorization - -[bearerAuth](README.md#bearerAuth) - -### HTTP request headers - - - **Content-Type**: Not defined - - **Accept**: application/json - - -### HTTP response details -| Status code | Description | Response headers | -|-------------|-------------|------------------| -**200** | Get metadata on all Lists | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**400** | Bad Request | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**0** | Errors | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| - -[[Back to top]](#) [[Back to API list]](README.md#documentation-for-api-endpoints) [[Back to Model list]](README.md#documentation-for-models) [[Back to README]](README.md) - -# **v2ListsListIdFieldsGET** -> FieldMetadataPaged v2ListsListIdFieldsGET() - -Returns metadata on the Fields available on a single List. Use the returned Field IDs to request field data from the GET `/v2/lists/{listId}/list-entries` endpoint. - -### Example - - -```typescript -import { createConfiguration, ListsApi } from '@planet-a/affinity-node/v2'; -import type { ListsApiV2ListsListIdFieldsGETRequest } from '@planet-a/affinity-node/v2'; - -const configuration = createConfiguration(); -const apiInstance = new ListsApi(configuration); - -const request: ListsApiV2ListsListIdFieldsGETRequest = { - // List ID - listId: 1, - // Cursor for the next or previous page (optional) - cursor: "cursor_example", - // Number of items to include in the page (optional) - limit: 100, -}; - -const data = await apiInstance.v2ListsListIdFieldsGET(request); -console.log('API called successfully. Returned data:', data); -``` - - -### Parameters - -Name | Type | Description | Notes -------------- | ------------- | ------------- | ------------- - **listId** | [**number**] | List ID | defaults to undefined - **cursor** | [**string**] | Cursor for the next or previous page | (optional) defaults to undefined - **limit** | [**number**] | Number of items to include in the page | (optional) defaults to 100 - - -### Return type - -**FieldMetadataPaged** - -### Authorization - -[bearerAuth](README.md#bearerAuth) - -### HTTP request headers - - - **Content-Type**: Not defined - - **Accept**: application/json - - -### HTTP response details -| Status code | Description | Response headers | -|-------------|-------------|------------------| -**200** | Get metadata on a single List\'s Fields | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**400** | Bad Request | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**404** | Not Found | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**0** | Errors | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| - -[[Back to top]](#) [[Back to API list]](README.md#documentation-for-api-endpoints) [[Back to Model list]](README.md#documentation-for-models) [[Back to README]](README.md) - -# **v2ListsListIdGET** -> ListWithType v2ListsListIdGET() - -Returns metadata on a single List. - -### Example - - -```typescript -import { createConfiguration, ListsApi } from '@planet-a/affinity-node/v2'; -import type { ListsApiV2ListsListIdGETRequest } from '@planet-a/affinity-node/v2'; - -const configuration = createConfiguration(); -const apiInstance = new ListsApi(configuration); - -const request: ListsApiV2ListsListIdGETRequest = { - // List ID - listId: 1, -}; - -const data = await apiInstance.v2ListsListIdGET(request); -console.log('API called successfully. Returned data:', data); -``` - - -### Parameters - -Name | Type | Description | Notes -------------- | ------------- | ------------- | ------------- - **listId** | [**number**] | List ID | defaults to undefined - - -### Return type - -**ListWithType** - -### Authorization - -[bearerAuth](README.md#bearerAuth) - -### HTTP request headers - - - **Content-Type**: Not defined - - **Accept**: application/json - - -### HTTP response details -| Status code | Description | Response headers | -|-------------|-------------|------------------| -**200** | Get metadata on a single List | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**400** | Bad Request | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**404** | Not Found | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**0** | Errors | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| - -[[Back to top]](#) [[Back to API list]](README.md#documentation-for-api-endpoints) [[Back to Model list]](README.md#documentation-for-models) [[Back to README]](README.md) - -# **v2ListsListIdListEntriesGET** -> ListEntryWithEntityPaged v2ListsListIdListEntriesGET() - -Paginate through the List Entries (AKA rows) on a given List. Returns basic information and field data, including list-specific field data, on each Company, Person, or Opportunity on the List. List Entries also include metadata about their creation, i.e., when they were added to the List and by whom. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/lists/{listId}/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, List Entries will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - -### Example - - -```typescript -import { createConfiguration, ListsApi } from '@planet-a/affinity-node/v2'; -import type { ListsApiV2ListsListIdListEntriesGETRequest } from '@planet-a/affinity-node/v2'; - -const configuration = createConfiguration(); -const apiInstance = new ListsApi(configuration); - -const request: ListsApiV2ListsListIdListEntriesGETRequest = { - // List ID - listId: 1, - // Cursor for the next or previous page (optional) - cursor: "cursor_example", - // Number of items to include in the page (optional) - limit: 100, - // Field IDs for which to return field data (optional) - fieldIds: [ - "fieldIds_example", - ], - // Field Types for which to return field data (optional) - fieldTypes: [ - "enriched", - ], -}; - -const data = await apiInstance.v2ListsListIdListEntriesGET(request); -console.log('API called successfully. Returned data:', data); -``` - - -### Parameters - -Name | Type | Description | Notes -------------- | ------------- | ------------- | ------------- - **listId** | [**number**] | List ID | defaults to undefined - **cursor** | [**string**] | Cursor for the next or previous page | (optional) defaults to undefined - **limit** | [**number**] | Number of items to include in the page | (optional) defaults to 100 - **fieldIds** | **Array<string>** | Field IDs for which to return field data | (optional) defaults to undefined - **fieldTypes** | **Array<'enriched' | 'global' | 'list' | 'relationship-intelligence'>** | Field Types for which to return field data | (optional) defaults to undefined - - -### Return type - -**ListEntryWithEntityPaged** - -### Authorization - -[bearerAuth](README.md#bearerAuth) - -### HTTP request headers - - - **Content-Type**: Not defined - - **Accept**: application/json - - -### HTTP response details -| Status code | Description | Response headers | -|-------------|-------------|------------------| -**200** | Get all List Entries on a List | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**400** | Bad Request | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**403** | Forbidden | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**404** | Not Found | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**0** | Errors | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| - -[[Back to top]](#) [[Back to API list]](README.md#documentation-for-api-endpoints) [[Back to Model list]](README.md#documentation-for-models) [[Back to README]](README.md) - -# **v2ListsListIdListEntriesListEntryIdFieldsFieldIdGET** -> Field v2ListsListIdListEntriesListEntryIdFieldsFieldIdGET() - - | ⚠️ This endpoint is currently in BETA | |--| Returns a single field value on a list entry. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - -### Example - - -```typescript -import { createConfiguration, ListsApi } from '@planet-a/affinity-node/v2'; -import type { ListsApiV2ListsListIdListEntriesListEntryIdFieldsFieldIdGETRequest } from '@planet-a/affinity-node/v2'; - -const configuration = createConfiguration(); -const apiInstance = new ListsApi(configuration); - -const request: ListsApiV2ListsListIdListEntriesListEntryIdFieldsFieldIdGETRequest = { - // List ID - listId: 1, - // List Entry ID - listEntryId: 1, - // Field ID - fieldId: "fieldId_example", -}; - -const data = await apiInstance.v2ListsListIdListEntriesListEntryIdFieldsFieldIdGET(request); -console.log('API called successfully. Returned data:', data); -``` - - -### Parameters - -Name | Type | Description | Notes -------------- | ------------- | ------------- | ------------- - **listId** | [**number**] | List ID | defaults to undefined - **listEntryId** | [**number**] | List Entry ID | defaults to undefined - **fieldId** | [**string**] | Field ID | defaults to undefined - - -### Return type - -**Field** - -### Authorization - -[bearerAuth](README.md#bearerAuth) - -### HTTP request headers - - - **Content-Type**: Not defined - - **Accept**: application/json - - -### HTTP response details -| Status code | Description | Response headers | -|-------------|-------------|------------------| -**200** | The field value | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**400** | Bad Request | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**403** | Forbidden | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**404** | Not Found | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**0** | Errors | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| - -[[Back to top]](#) [[Back to API list]](README.md#documentation-for-api-endpoints) [[Back to Model list]](README.md#documentation-for-models) [[Back to README]](README.md) - -# **v2ListsListIdListEntriesListEntryIdFieldsFieldIdPOST** -> void v2ListsListIdListEntriesListEntryIdFieldsFieldIdPOST(fieldUpdate) - - | ⚠️ This endpoint is currently in BETA | |--| Update a single field value. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - -### Example - - -```typescript -import { createConfiguration, ListsApi } from '@planet-a/affinity-node/v2'; -import type { ListsApiV2ListsListIdListEntriesListEntryIdFieldsFieldIdPOSTRequest } from '@planet-a/affinity-node/v2'; - -const configuration = createConfiguration(); -const apiInstance = new ListsApi(configuration); - -const request: ListsApiV2ListsListIdListEntriesListEntryIdFieldsFieldIdPOSTRequest = { - // List ID - listId: 1, - // List Entry ID - listEntryId: 1, - // Field ID - fieldId: "fieldId_example", - - fieldUpdate: { - value: null, - }, -}; - -const data = await apiInstance.v2ListsListIdListEntriesListEntryIdFieldsFieldIdPOST(request); -console.log('API called successfully. Returned data:', data); -``` - - -### Parameters - -Name | Type | Description | Notes -------------- | ------------- | ------------- | ------------- - **fieldUpdate** | **FieldUpdate**| | - **listId** | [**number**] | List ID | defaults to undefined - **listEntryId** | [**number**] | List Entry ID | defaults to undefined - **fieldId** | [**string**] | Field ID | defaults to undefined - - -### Return type - -**void** - -### Authorization - -[bearerAuth](README.md#bearerAuth) - -### HTTP request headers - - - **Content-Type**: application/json - - **Accept**: application/json - - -### HTTP response details -| Status code | Description | Response headers | -|-------------|-------------|------------------| -**204** | No Content | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**400** | Bad Request | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**403** | Forbidden | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**404** | Not Found | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**0** | Errors | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| - -[[Back to top]](#) [[Back to API list]](README.md#documentation-for-api-endpoints) [[Back to Model list]](README.md#documentation-for-models) [[Back to README]](README.md) - -# **v2ListsListIdListEntriesListEntryIdFieldsGET** -> FieldPaged v2ListsListIdListEntriesListEntryIdFieldsGET() - - | ⚠️ This endpoint is currently in BETA | |--| Paginate through all field values on a single list entry. All fields will be included by default. The `ids` and `types` parameters can be used to filter the collection. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - -### Example - - -```typescript -import { createConfiguration, ListsApi } from '@planet-a/affinity-node/v2'; -import type { ListsApiV2ListsListIdListEntriesListEntryIdFieldsGETRequest } from '@planet-a/affinity-node/v2'; - -const configuration = createConfiguration(); -const apiInstance = new ListsApi(configuration); - -const request: ListsApiV2ListsListIdListEntriesListEntryIdFieldsGETRequest = { - // List ID - listId: 1, - // List Entry ID - listEntryId: 1, - // Field IDs for which to return field data (optional) - ids: [ - "ids_example", - ], - // Field Types for which to return field data (optional) - types: [ - "enriched", - ], - // Cursor for the next or previous page (optional) - cursor: "cursor_example", - // Number of items to include in the page (optional) - limit: 20, -}; - -const data = await apiInstance.v2ListsListIdListEntriesListEntryIdFieldsGET(request); -console.log('API called successfully. Returned data:', data); -``` - - -### Parameters - -Name | Type | Description | Notes -------------- | ------------- | ------------- | ------------- - **listId** | [**number**] | List ID | defaults to undefined - **listEntryId** | [**number**] | List Entry ID | defaults to undefined - **ids** | **Array<string>** | Field IDs for which to return field data | (optional) defaults to undefined - **types** | **Array<'enriched' | 'global' | 'list' | 'relationship-intelligence'>** | Field Types for which to return field data | (optional) defaults to undefined - **cursor** | [**string**] | Cursor for the next or previous page | (optional) defaults to undefined - **limit** | [**number**] | Number of items to include in the page | (optional) defaults to 20 - - -### Return type - -**FieldPaged** - -### Authorization - -[bearerAuth](README.md#bearerAuth) - -### HTTP request headers - - - **Content-Type**: Not defined - - **Accept**: application/json - - -### HTTP response details -| Status code | Description | Response headers | -|-------------|-------------|------------------| -**200** | Paginated fields | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**400** | Bad Request | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**403** | Forbidden | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**404** | Not Found | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**0** | Errors | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| - -[[Back to top]](#) [[Back to API list]](README.md#documentation-for-api-endpoints) [[Back to Model list]](README.md#documentation-for-models) [[Back to README]](README.md) - -# **v2ListsListIdListEntriesListEntryIdFieldsPATCH** -> ListEntryBatchOperationResponse v2ListsListIdListEntriesListEntryIdFieldsPATCH(body) - -| ⚠️ This endpoint is currently in BETA | |--| Perform batch operations on a list entry\'s fields. Currently the only operation at the endpoint is `update-fields`, which allows you to update multiple field values with a single request. This is equivalent to calling [the single field update](#operation/v2_lists_listId_list-entries_listEntryId_fields_fieldId__POST) endpoint multiple times. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - -### Example - - -```typescript -import { createConfiguration, ListsApi } from '@planet-a/affinity-node/v2'; -import type { ListsApiV2ListsListIdListEntriesListEntryIdFieldsPATCHRequest } from '@planet-a/affinity-node/v2'; - -const configuration = createConfiguration(); -const apiInstance = new ListsApi(configuration); - -const request: ListsApiV2ListsListIdListEntriesListEntryIdFieldsPATCHRequest = { - // List ID - listId: 1, - // List Entry ID - listEntryId: 1, - - body: { - operation: "update-fields", - updates: [ - { - id: "id_example", - value: null, - }, - ], - }, -}; - -const data = await apiInstance.v2ListsListIdListEntriesListEntryIdFieldsPATCH(request); -console.log('API called successfully. Returned data:', data); -``` - - -### Parameters - -Name | Type | Description | Notes -------------- | ------------- | ------------- | ------------- - **body** | **ListEntryBatchOperationUpdateFields**| | - **listId** | [**number**] | List ID | defaults to undefined - **listEntryId** | [**number**] | List Entry ID | defaults to undefined - - -### Return type - -**ListEntryBatchOperationResponse** - -### Authorization - -[bearerAuth](README.md#bearerAuth) - -### HTTP request headers - - - **Content-Type**: application/json - - **Accept**: application/json - - -### HTTP response details -| Status code | Description | Response headers | -|-------------|-------------|------------------| -**200** | Operation Result | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**400** | Bad Request | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**403** | Forbidden | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**404** | Not Found | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**0** | Errors | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| - -[[Back to top]](#) [[Back to API list]](README.md#documentation-for-api-endpoints) [[Back to Model list]](README.md#documentation-for-models) [[Back to README]](README.md) - -# **v2ListsListIdListEntriesListEntryIdGET** -> ListEntryWithEntity v2ListsListIdListEntriesListEntryIdGET() - -| ⚠️ This endpoint is currently in BETA | |--| Retrieve a single list entry. Returns basic information and field data, including list-specific field data. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/lists/{listId}/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, the List Entry will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - -### Example - - -```typescript -import { createConfiguration, ListsApi } from '@planet-a/affinity-node/v2'; -import type { ListsApiV2ListsListIdListEntriesListEntryIdGETRequest } from '@planet-a/affinity-node/v2'; - -const configuration = createConfiguration(); -const apiInstance = new ListsApi(configuration); - -const request: ListsApiV2ListsListIdListEntriesListEntryIdGETRequest = { - // List ID - listId: 1, - // List Entry ID - listEntryId: 1, - // Field IDs for which to return field data (optional) - fieldIds: [ - "fieldIds_example", - ], - // Field Types for which to return field data (optional) - fieldTypes: [ - "enriched", - ], -}; - -const data = await apiInstance.v2ListsListIdListEntriesListEntryIdGET(request); -console.log('API called successfully. Returned data:', data); -``` - - -### Parameters - -Name | Type | Description | Notes -------------- | ------------- | ------------- | ------------- - **listId** | [**number**] | List ID | defaults to undefined - **listEntryId** | [**number**] | List Entry ID | defaults to undefined - **fieldIds** | **Array<string>** | Field IDs for which to return field data | (optional) defaults to undefined - **fieldTypes** | **Array<'enriched' | 'global' | 'list' | 'relationship-intelligence'>** | Field Types for which to return field data | (optional) defaults to undefined - - -### Return type - -**ListEntryWithEntity** - -### Authorization - -[bearerAuth](README.md#bearerAuth) - -### HTTP request headers - - - **Content-Type**: Not defined - - **Accept**: application/json - - -### HTTP response details -| Status code | Description | Response headers | -|-------------|-------------|------------------| -**200** | The list entry | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**400** | Bad Request | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**403** | Forbidden | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**404** | Not Found | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**0** | Errors | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| - -[[Back to top]](#) [[Back to API list]](README.md#documentation-for-api-endpoints) [[Back to Model list]](README.md#documentation-for-models) [[Back to README]](README.md) - - diff --git a/src/v2/generated/OpportunitiesApi.md b/src/v2/generated/OpportunitiesApi.md deleted file mode 100644 index f67f2f8..0000000 --- a/src/v2/generated/OpportunitiesApi.md +++ /dev/null @@ -1,133 +0,0 @@ -# Affinity.OpportunitiesApi - -All URIs are relative to *https://api.affinity.co* - -Method | HTTP request | Description -------------- | ------------- | ------------- -[**getV2Opportunities**](OpportunitiesApi.md#getV2Opportunities) | **GET** /v2/opportunities | Get all Opportunities -[**getV2OpportunitiesId**](OpportunitiesApi.md#getV2OpportunitiesId) | **GET** /v2/opportunities/{id} | Get a single Opportunity - - -# **getV2Opportunities** -> OpportunityPaged getV2Opportunities() - -Paginate through Opportunities in Affinity. Returns basic information but **not** field data on each Opportunity. To access field data on Opportunities, use the `/lists/{list_id}/list-entries` or the `/v2/lists/{list_id}/saved-views/{view_id}/list-entries` GET endpoint. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - -### Example - - -```typescript -import { createConfiguration, OpportunitiesApi } from '@planet-a/affinity-node/v2'; -import type { OpportunitiesApiGetV2OpportunitiesRequest } from '@planet-a/affinity-node/v2'; - -const configuration = createConfiguration(); -const apiInstance = new OpportunitiesApi(configuration); - -const request: OpportunitiesApiGetV2OpportunitiesRequest = { - // Cursor for the next or previous page (optional) - cursor: "cursor_example", - // Number of items to include in the page (optional) - limit: 100, - // Opportunity IDs (optional) - ids: [ - 1, - ], -}; - -const data = await apiInstance.getV2Opportunities(request); -console.log('API called successfully. Returned data:', data); -``` - - -### Parameters - -Name | Type | Description | Notes -------------- | ------------- | ------------- | ------------- - **cursor** | [**string**] | Cursor for the next or previous page | (optional) defaults to undefined - **limit** | [**number**] | Number of items to include in the page | (optional) defaults to 100 - **ids** | **Array<number>** | Opportunity IDs | (optional) defaults to undefined - - -### Return type - -**OpportunityPaged** - -### Authorization - -[bearerAuth](README.md#bearerAuth) - -### HTTP request headers - - - **Content-Type**: Not defined - - **Accept**: application/json - - -### HTTP response details -| Status code | Description | Response headers | -|-------------|-------------|------------------| -**200** | Get all Opportunities | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**400** | Bad Request | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**403** | Forbidden | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**404** | Not Found | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**0** | Errors | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| - -[[Back to top]](#) [[Back to API list]](README.md#documentation-for-api-endpoints) [[Back to Model list]](README.md#documentation-for-models) [[Back to README]](README.md) - -# **getV2OpportunitiesId** -> Opportunity getV2OpportunitiesId() - -Returns basic information but **not** field data on the requested Opportunity. To access field data on Opportunities, use the `/lists/{list_id}/list-entries` or the `/v2/lists/{list_id}/saved-views/{view_id}/list-entries` GET endpoint. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - -### Example - - -```typescript -import { createConfiguration, OpportunitiesApi } from '@planet-a/affinity-node/v2'; -import type { OpportunitiesApiGetV2OpportunitiesIdRequest } from '@planet-a/affinity-node/v2'; - -const configuration = createConfiguration(); -const apiInstance = new OpportunitiesApi(configuration); - -const request: OpportunitiesApiGetV2OpportunitiesIdRequest = { - // Opportunity ID - id: 1, -}; - -const data = await apiInstance.getV2OpportunitiesId(request); -console.log('API called successfully. Returned data:', data); -``` - - -### Parameters - -Name | Type | Description | Notes -------------- | ------------- | ------------- | ------------- - **id** | [**number**] | Opportunity ID | defaults to undefined - - -### Return type - -**Opportunity** - -### Authorization - -[bearerAuth](README.md#bearerAuth) - -### HTTP request headers - - - **Content-Type**: Not defined - - **Accept**: application/json - - -### HTTP response details -| Status code | Description | Response headers | -|-------------|-------------|------------------| -**200** | Get a single Opportunity | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**400** | Bad Request | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**403** | Forbidden | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**404** | Not Found | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**0** | Errors | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| - -[[Back to top]](#) [[Back to API list]](README.md#documentation-for-api-endpoints) [[Back to Model list]](README.md#documentation-for-models) [[Back to README]](README.md) - - diff --git a/src/v2/generated/PersonsApi.md b/src/v2/generated/PersonsApi.md deleted file mode 100644 index c2d5511..0000000 --- a/src/v2/generated/PersonsApi.md +++ /dev/null @@ -1,338 +0,0 @@ -# Affinity.PersonsApi - -All URIs are relative to *https://api.affinity.co* - -Method | HTTP request | Description -------------- | ------------- | ------------- -[**getV2Persons**](PersonsApi.md#getV2Persons) | **GET** /v2/persons | Get all Persons -[**getV2PersonsFields**](PersonsApi.md#getV2PersonsFields) | **GET** /v2/persons/fields | Get metadata on Person Fields -[**getV2PersonsId**](PersonsApi.md#getV2PersonsId) | **GET** /v2/persons/{id} | Get a single Person -[**getV2PersonsIdListEntries**](PersonsApi.md#getV2PersonsIdListEntries) | **GET** /v2/persons/{id}/list-entries | Get a Person\'s List Entries -[**getV2PersonsIdLists**](PersonsApi.md#getV2PersonsIdLists) | **GET** /v2/persons/{id}/lists | Get a Person\'s Lists - - -# **getV2Persons** -> PersonPaged getV2Persons() - -Paginate through Persons in Affinity. Returns basic information and non-list-specific field data on each Person. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/persons/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Persons will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All People directory\" [permission](#section/Getting-Started/Permissions). - -### Example - - -```typescript -import { createConfiguration, PersonsApi } from '@planet-a/affinity-node/v2'; -import type { PersonsApiGetV2PersonsRequest } from '@planet-a/affinity-node/v2'; - -const configuration = createConfiguration(); -const apiInstance = new PersonsApi(configuration); - -const request: PersonsApiGetV2PersonsRequest = { - // Cursor for the next or previous page (optional) - cursor: "cursor_example", - // Number of items to include in the page (optional) - limit: 100, - // People IDs (optional) - ids: [ - 1, - ], - // Field IDs for which to return field data (optional) - fieldIds: [ - "fieldIds_example", - ], - // Field Types for which to return field data (optional) - fieldTypes: [ - "enriched", - ], -}; - -const data = await apiInstance.getV2Persons(request); -console.log('API called successfully. Returned data:', data); -``` - - -### Parameters - -Name | Type | Description | Notes -------------- | ------------- | ------------- | ------------- - **cursor** | [**string**] | Cursor for the next or previous page | (optional) defaults to undefined - **limit** | [**number**] | Number of items to include in the page | (optional) defaults to 100 - **ids** | **Array<number>** | People IDs | (optional) defaults to undefined - **fieldIds** | **Array<string>** | Field IDs for which to return field data | (optional) defaults to undefined - **fieldTypes** | **Array<'enriched' | 'global' | 'relationship-intelligence'>** | Field Types for which to return field data | (optional) defaults to undefined - - -### Return type - -**PersonPaged** - -### Authorization - -[bearerAuth](README.md#bearerAuth) - -### HTTP request headers - - - **Content-Type**: Not defined - - **Accept**: application/json - - -### HTTP response details -| Status code | Description | Response headers | -|-------------|-------------|------------------| -**200** | Get all Persons | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**400** | Bad Request | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**403** | Forbidden | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**0** | Errors | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| - -[[Back to top]](#) [[Back to API list]](README.md#documentation-for-api-endpoints) [[Back to Model list]](README.md#documentation-for-models) [[Back to README]](README.md) - -# **getV2PersonsFields** -> FieldMetadataPaged getV2PersonsFields() - -Returns metadata on non-list-specific Person Fields. Use the returned Field IDs to request field data from the GET `/v2/persons` and GET `/v2/persons/{id}` endpoints. - -### Example - - -```typescript -import { createConfiguration, PersonsApi } from '@planet-a/affinity-node/v2'; -import type { PersonsApiGetV2PersonsFieldsRequest } from '@planet-a/affinity-node/v2'; - -const configuration = createConfiguration(); -const apiInstance = new PersonsApi(configuration); - -const request: PersonsApiGetV2PersonsFieldsRequest = { - // Cursor for the next or previous page (optional) - cursor: "cursor_example", - // Number of items to include in the page (optional) - limit: 100, -}; - -const data = await apiInstance.getV2PersonsFields(request); -console.log('API called successfully. Returned data:', data); -``` - - -### Parameters - -Name | Type | Description | Notes -------------- | ------------- | ------------- | ------------- - **cursor** | [**string**] | Cursor for the next or previous page | (optional) defaults to undefined - **limit** | [**number**] | Number of items to include in the page | (optional) defaults to 100 - - -### Return type - -**FieldMetadataPaged** - -### Authorization - -[bearerAuth](README.md#bearerAuth) - -### HTTP request headers - - - **Content-Type**: Not defined - - **Accept**: application/json - - -### HTTP response details -| Status code | Description | Response headers | -|-------------|-------------|------------------| -**200** | Get metadata on Person Fields | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**400** | Bad Request | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**0** | Errors | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| - -[[Back to top]](#) [[Back to API list]](README.md#documentation-for-api-endpoints) [[Back to Model list]](README.md#documentation-for-models) [[Back to README]](README.md) - -# **getV2PersonsId** -> Person getV2PersonsId() - -Returns basic information and non-list-specific field data on the requested Person. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/persons/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Persons will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All People directory\" [permission](#section/Getting-Started/Permissions). - -### Example - - -```typescript -import { createConfiguration, PersonsApi } from '@planet-a/affinity-node/v2'; -import type { PersonsApiGetV2PersonsIdRequest } from '@planet-a/affinity-node/v2'; - -const configuration = createConfiguration(); -const apiInstance = new PersonsApi(configuration); - -const request: PersonsApiGetV2PersonsIdRequest = { - // Person ID - id: 1, - // Field IDs for which to return field data (optional) - fieldIds: [ - "fieldIds_example", - ], - // Field Types for which to return field data (optional) - fieldTypes: [ - "enriched", - ], -}; - -const data = await apiInstance.getV2PersonsId(request); -console.log('API called successfully. Returned data:', data); -``` - - -### Parameters - -Name | Type | Description | Notes -------------- | ------------- | ------------- | ------------- - **id** | [**number**] | Person ID | defaults to undefined - **fieldIds** | **Array<string>** | Field IDs for which to return field data | (optional) defaults to undefined - **fieldTypes** | **Array<'enriched' | 'global' | 'relationship-intelligence'>** | Field Types for which to return field data | (optional) defaults to undefined - - -### Return type - -**Person** - -### Authorization - -[bearerAuth](README.md#bearerAuth) - -### HTTP request headers - - - **Content-Type**: Not defined - - **Accept**: application/json - - -### HTTP response details -| Status code | Description | Response headers | -|-------------|-------------|------------------| -**200** | Get a single Person | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**400** | Bad Request | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**403** | Forbidden | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**404** | Not Found | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**0** | Errors | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| - -[[Back to top]](#) [[Back to API list]](README.md#documentation-for-api-endpoints) [[Back to Model list]](README.md#documentation-for-models) [[Back to README]](README.md) - -# **getV2PersonsIdListEntries** -> ListEntryPaged getV2PersonsIdListEntries() - -Paginate through the List Entries (AKA rows) for the given Person across all Lists. Each List Entry includes field data for the Person, including list-specific field data. Each List Entry also includes metadata about its creation, i.e., when it was added to the List and by whom. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - -### Example - - -```typescript -import { createConfiguration, PersonsApi } from '@planet-a/affinity-node/v2'; -import type { PersonsApiGetV2PersonsIdListEntriesRequest } from '@planet-a/affinity-node/v2'; - -const configuration = createConfiguration(); -const apiInstance = new PersonsApi(configuration); - -const request: PersonsApiGetV2PersonsIdListEntriesRequest = { - // Persons ID - id: 1, - // Cursor for the next or previous page (optional) - cursor: "cursor_example", - // Number of items to include in the page (optional) - limit: 100, -}; - -const data = await apiInstance.getV2PersonsIdListEntries(request); -console.log('API called successfully. Returned data:', data); -``` - - -### Parameters - -Name | Type | Description | Notes -------------- | ------------- | ------------- | ------------- - **id** | [**number**] | Persons ID | defaults to undefined - **cursor** | [**string**] | Cursor for the next or previous page | (optional) defaults to undefined - **limit** | [**number**] | Number of items to include in the page | (optional) defaults to 100 - - -### Return type - -**ListEntryPaged** - -### Authorization - -[bearerAuth](README.md#bearerAuth) - -### HTTP request headers - - - **Content-Type**: Not defined - - **Accept**: application/json - - -### HTTP response details -| Status code | Description | Response headers | -|-------------|-------------|------------------| -**200** | Get a Person\'s List Entries | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**400** | Bad Request | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**403** | Forbidden | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**404** | Not Found | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**0** | Errors | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| - -[[Back to top]](#) [[Back to API list]](README.md#documentation-for-api-endpoints) [[Back to Model list]](README.md#documentation-for-models) [[Back to README]](README.md) - -# **getV2PersonsIdLists** -> ListPaged getV2PersonsIdLists() - -Returns metadata for all the Lists on which the given Person appears. - -### Example - - -```typescript -import { createConfiguration, PersonsApi } from '@planet-a/affinity-node/v2'; -import type { PersonsApiGetV2PersonsIdListsRequest } from '@planet-a/affinity-node/v2'; - -const configuration = createConfiguration(); -const apiInstance = new PersonsApi(configuration); - -const request: PersonsApiGetV2PersonsIdListsRequest = { - // Persons ID - id: 1, - // Cursor for the next or previous page (optional) - cursor: "cursor_example", - // Number of items to include in the page (optional) - limit: 100, -}; - -const data = await apiInstance.getV2PersonsIdLists(request); -console.log('API called successfully. Returned data:', data); -``` - - -### Parameters - -Name | Type | Description | Notes -------------- | ------------- | ------------- | ------------- - **id** | [**number**] | Persons ID | defaults to undefined - **cursor** | [**string**] | Cursor for the next or previous page | (optional) defaults to undefined - **limit** | [**number**] | Number of items to include in the page | (optional) defaults to 100 - - -### Return type - -**ListPaged** - -### Authorization - -[bearerAuth](README.md#bearerAuth) - -### HTTP request headers - - - **Content-Type**: Not defined - - **Accept**: application/json - - -### HTTP response details -| Status code | Description | Response headers | -|-------------|-------------|------------------| -**200** | Get a Person\'s Lists | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**400** | Bad Request | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**404** | Not Found | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| -**0** | Errors | * X-Ratelimit-Limit-User -
* X-Ratelimit-Limit-User-Remaining -
* X-Ratelimit-Limit-User-Reset -
* X-Ratelimit-Limit-Org -
* X-Ratelimit-Limit-Org-Remaining -
* X-Ratelimit-Limit-Org-Reset -
| - -[[Back to top]](#) [[Back to API list]](README.md#documentation-for-api-endpoints) [[Back to Model list]](README.md#documentation-for-models) [[Back to README]](README.md) - - diff --git a/src/v2/generated/apis/AuthApi.ts b/src/v2/generated/apis/AuthApi.ts index 9f823c9..a30b2a1 100644 --- a/src/v2/generated/apis/AuthApi.ts +++ b/src/v2/generated/apis/AuthApi.ts @@ -18,10 +18,10 @@ import { WhoAmI } from '../models/WhoAmI.ts'; export class AuthApiRequestFactory extends BaseAPIRequestFactory { /** - * Returns metadata about the current user. + * Returns information about the authenticated user, their current organization, and API key permissions. Use this endpoint to verify your authentication and understand your available API access levels. * Get current user */ - public async getV2AuthWhoami(_options?: Configuration): Promise { + public async v2AuthWhoamiGET(_options?: Configuration): Promise { let _config = _options || this.configuration; // Path Params @@ -55,10 +55,10 @@ export class AuthApiResponseProcessor { * Unwraps the actual response sent by the server from the response context and deserializes the response content * to the expected objects * - * @params response Response returned by the server for a request to getV2AuthWhoami + * @params response Response returned by the server for a request to v2AuthWhoamiGET * @throws ApiException if the response code was not in [200, 299] */ - public async getV2AuthWhoamiWithHttpInfo(response: ResponseContext): Promise> { + public async v2AuthWhoamiGETWithHttpInfo(response: ResponseContext): Promise> { const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); if (isCodeInRange("200", response.httpStatusCode)) { const body: WhoAmI = ObjectSerializer.deserialize( diff --git a/src/v2/generated/apis/CallsApi.ts b/src/v2/generated/apis/CallsApi.ts new file mode 100644 index 0000000..40ddeb0 --- /dev/null +++ b/src/v2/generated/apis/CallsApi.ts @@ -0,0 +1,118 @@ +// TODO: better import syntax? +import {BaseAPIRequestFactory, RequiredError, COLLECTION_FORMATS} from './baseapi.ts'; +import {Configuration} from '../configuration.ts'; +import {RequestContext, HttpMethod, ResponseContext, HttpFile, HttpInfo} from '../http/http.ts'; +import {ObjectSerializer} from '../models/ObjectSerializer.ts'; +import {ApiException} from './exception.ts'; +import {canConsumeForm, isCodeInRange} from '../util.ts'; +import {SecurityAuthentication} from '../auth/auth.ts'; + + +import { Errors } from '../models/Errors.ts'; +import { InteractionsCallPaged } from '../models/InteractionsCallPaged.ts'; +import { Responses400 } from '../models/Responses400.ts'; + +/** + * no description + */ +export class CallsApiRequestFactory extends BaseAPIRequestFactory { + + /** + * Paginate through all calls in Affinity. Returns basic information about the call interaction and its participants. Will only return calls that the current authenticated user has permission to see. You can filter calls using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|----------------------------------| | `id` | Unique identifier for Calls | `int64` | `=` | `id=1` | | `startTime` | Start time of when the Call was held | `datetime` | `>`, `<`, `>=`, `<=` | `sentAt>2025-01-01T01:00:00Z` | | `createdAt` | When the Call was created in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-01-01T01:00:00Z` | | `updatedAt` | When the Call was updated in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-01-01T01:00:00Z`| + * Get metadata on all Calls + * @param cursor Cursor for the next or previous page + * @param limit Number of items to include in the page + * @param filter Filter options + */ + public async v2CallsGET(cursor?: string, limit?: number, filter?: string, _options?: Configuration): Promise { + let _config = _options || this.configuration; + + + + + // Path Params + const localVarPath = '/v2/calls'; + + // Make Request Context + const requestContext = _config.baseServer.makeRequestContext(localVarPath, HttpMethod.GET); + requestContext.setHeaderParam("Accept", "application/json, */*;q=0.8") + + // Query Params + if (cursor !== undefined) { + requestContext.setQueryParam("cursor", ObjectSerializer.serialize(cursor, "string", "")); + } + + // Query Params + if (limit !== undefined) { + requestContext.setQueryParam("limit", ObjectSerializer.serialize(limit, "number", "int32")); + } + + // Query Params + if (filter !== undefined) { + requestContext.setQueryParam("filter", ObjectSerializer.serialize(filter, "string", "")); + } + + + let authMethod: SecurityAuthentication | undefined; + // Apply auth methods + authMethod = _config.authMethods["bearerAuth"] + if (authMethod?.applySecurityAuthentication) { + await authMethod?.applySecurityAuthentication(requestContext); + } + + const defaultAuth: SecurityAuthentication | undefined = _config?.authMethods?.default + if (defaultAuth?.applySecurityAuthentication) { + await defaultAuth?.applySecurityAuthentication(requestContext); + } + + return requestContext; + } + +} + +export class CallsApiResponseProcessor { + + /** + * Unwraps the actual response sent by the server from the response context and deserializes the response content + * to the expected objects + * + * @params response Response returned by the server for a request to v2CallsGET + * @throws ApiException if the response code was not in [200, 299] + */ + public async v2CallsGETWithHttpInfo(response: ResponseContext): Promise> { + const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); + if (isCodeInRange("200", response.httpStatusCode)) { + const body: InteractionsCallPaged = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "InteractionsCallPaged", "" + ) as InteractionsCallPaged; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + if (isCodeInRange("400", response.httpStatusCode)) { + const body: Responses400 = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + } + if (isCodeInRange("0", response.httpStatusCode)) { + const body: Errors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Errors", "" + ) as Errors; + throw new ApiException(response.httpStatusCode, "Errors", body, response.headers); + } + + // Work around for missing responses in specification, e.g. for petstore.yaml + if (response.httpStatusCode >= 200 && response.httpStatusCode <= 299) { + const body: InteractionsCallPaged = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "InteractionsCallPaged", "" + ) as InteractionsCallPaged; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + + throw new ApiException(response.httpStatusCode, "Unknown API Status Code!", await response.getBodyAsAny(), response.headers); + } + +} diff --git a/src/v2/generated/apis/ChatMessagesApi.ts b/src/v2/generated/apis/ChatMessagesApi.ts new file mode 100644 index 0000000..d64a7c4 --- /dev/null +++ b/src/v2/generated/apis/ChatMessagesApi.ts @@ -0,0 +1,118 @@ +// TODO: better import syntax? +import {BaseAPIRequestFactory, RequiredError, COLLECTION_FORMATS} from './baseapi.ts'; +import {Configuration} from '../configuration.ts'; +import {RequestContext, HttpMethod, ResponseContext, HttpFile, HttpInfo} from '../http/http.ts'; +import {ObjectSerializer} from '../models/ObjectSerializer.ts'; +import {ApiException} from './exception.ts'; +import {canConsumeForm, isCodeInRange} from '../util.ts'; +import {SecurityAuthentication} from '../auth/auth.ts'; + + +import { Errors } from '../models/Errors.ts'; +import { InteractionsChatMessagePaged } from '../models/InteractionsChatMessagePaged.ts'; +import { Responses400 } from '../models/Responses400.ts'; + +/** + * no description + */ +export class ChatMessagesApiRequestFactory extends BaseAPIRequestFactory { + + /** + * Paginate through all chat messages in Affinity. Returns basic information about the chat message interaction and its participants. Will only return chat messages that the current authenticated user has permission to see. You can filter chat messages using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|----------------------------------| | `id` | Unique identifier for Chat Messages | `int64` | `=` | `id=1` | | `sentAt` | When the Chat Message was sent at | `datetime` | `>`, `<`, `>=`, `<=` | `sentAt>2025-01-01T01:00:00Z` | | `createdAt` | When the Chat Message was created in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-01-01T01:00:00Z` | | `updatedAt` | When the Chat Message was updated in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-01-01T01:00:00Z`| + * Get metadata on all Chat Messages + * @param cursor Cursor for the next or previous page + * @param limit Number of items to include in the page + * @param filter Filter options + */ + public async v2ChatMessagesGET(cursor?: string, limit?: number, filter?: string, _options?: Configuration): Promise { + let _config = _options || this.configuration; + + + + + // Path Params + const localVarPath = '/v2/chat-messages'; + + // Make Request Context + const requestContext = _config.baseServer.makeRequestContext(localVarPath, HttpMethod.GET); + requestContext.setHeaderParam("Accept", "application/json, */*;q=0.8") + + // Query Params + if (cursor !== undefined) { + requestContext.setQueryParam("cursor", ObjectSerializer.serialize(cursor, "string", "")); + } + + // Query Params + if (limit !== undefined) { + requestContext.setQueryParam("limit", ObjectSerializer.serialize(limit, "number", "int32")); + } + + // Query Params + if (filter !== undefined) { + requestContext.setQueryParam("filter", ObjectSerializer.serialize(filter, "string", "")); + } + + + let authMethod: SecurityAuthentication | undefined; + // Apply auth methods + authMethod = _config.authMethods["bearerAuth"] + if (authMethod?.applySecurityAuthentication) { + await authMethod?.applySecurityAuthentication(requestContext); + } + + const defaultAuth: SecurityAuthentication | undefined = _config?.authMethods?.default + if (defaultAuth?.applySecurityAuthentication) { + await defaultAuth?.applySecurityAuthentication(requestContext); + } + + return requestContext; + } + +} + +export class ChatMessagesApiResponseProcessor { + + /** + * Unwraps the actual response sent by the server from the response context and deserializes the response content + * to the expected objects + * + * @params response Response returned by the server for a request to v2ChatMessagesGET + * @throws ApiException if the response code was not in [200, 299] + */ + public async v2ChatMessagesGETWithHttpInfo(response: ResponseContext): Promise> { + const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); + if (isCodeInRange("200", response.httpStatusCode)) { + const body: InteractionsChatMessagePaged = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "InteractionsChatMessagePaged", "" + ) as InteractionsChatMessagePaged; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + if (isCodeInRange("400", response.httpStatusCode)) { + const body: Responses400 = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + } + if (isCodeInRange("0", response.httpStatusCode)) { + const body: Errors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Errors", "" + ) as Errors; + throw new ApiException(response.httpStatusCode, "Errors", body, response.headers); + } + + // Work around for missing responses in specification, e.g. for petstore.yaml + if (response.httpStatusCode >= 200 && response.httpStatusCode <= 299) { + const body: InteractionsChatMessagePaged = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "InteractionsChatMessagePaged", "" + ) as InteractionsChatMessagePaged; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + + throw new ApiException(response.httpStatusCode, "Unknown API Status Code!", await response.getBodyAsAny(), response.headers); + } + +} diff --git a/src/v2/generated/apis/CompaniesApi.ts b/src/v2/generated/apis/CompaniesApi.ts index f1aceb6..471aa1b 100644 --- a/src/v2/generated/apis/CompaniesApi.ts +++ b/src/v2/generated/apis/CompaniesApi.ts @@ -13,10 +13,11 @@ import { Company } from '../models/Company.ts'; import { CompanyPaged } from '../models/CompanyPaged.ts'; import { Errors } from '../models/Errors.ts'; import { FieldMetadataPaged } from '../models/FieldMetadataPaged.ts'; -import { InlineObject } from '../models/InlineObject.ts'; import { ListEntryPaged } from '../models/ListEntryPaged.ts'; import { ListPaged } from '../models/ListPaged.ts'; import { NotFoundErrors } from '../models/NotFoundErrors.ts'; +import { NotesNotesPaged } from '../models/NotesNotesPaged.ts'; +import { Responses400 } from '../models/Responses400.ts'; /** * no description @@ -24,50 +25,34 @@ import { NotFoundErrors } from '../models/NotFoundErrors.ts'; export class CompaniesApiRequestFactory extends BaseAPIRequestFactory { /** - * Paginate through Companies in Affinity. Returns basic information and non-list-specific field data on each Company. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/companies/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Companies will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All Organizations directory\" [permission](#section/Getting-Started/Permissions). - * Get all Companies - * @param cursor Cursor for the next or previous page - * @param limit Number of items to include in the page - * @param ids Company IDs + * Returns basic information and non-list-specific field data on the requested Company. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/companies/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Companies will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All Organizations directory\" [permission](#section/Getting-Started/Permissions). + * Get a single Company + * @param companyId Company ID * @param fieldIds Field IDs for which to return field data * @param fieldTypes Field Types for which to return field data */ - public async getV2Companies(cursor?: string, limit?: number, ids?: Array, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: Configuration): Promise { + public async v2CompaniesCompanyIdGET(companyId: number, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: Configuration): Promise { let _config = _options || this.configuration; - + // verify required parameter 'companyId' is not null or undefined + if (companyId === null || companyId === undefined) { + throw new RequiredError("CompaniesApi", "v2CompaniesCompanyIdGET", "companyId"); + } // Path Params - const localVarPath = '/v2/companies'; + const localVarPath = '/v2/companies/{companyId}' + .replace('{' + 'companyId' + '}', encodeURIComponent(String(companyId))); // Make Request Context const requestContext = _config.baseServer.makeRequestContext(localVarPath, HttpMethod.GET); requestContext.setHeaderParam("Accept", "application/json, */*;q=0.8") - // Query Params - if (cursor !== undefined) { - requestContext.setQueryParam("cursor", ObjectSerializer.serialize(cursor, "string", "")); - } - - // Query Params - if (limit !== undefined) { - requestContext.setQueryParam("limit", ObjectSerializer.serialize(limit, "number", "int32")); - } - - // Query Params - if (ids !== undefined) { - const serializedParams = ObjectSerializer.serialize(ids, "Array", "int64"); - for (const serializedParam of serializedParams) { - requestContext.appendQueryParam("ids", serializedParam); - } - } - // Query Params if (fieldIds !== undefined) { - const serializedParams = ObjectSerializer.serialize(fieldIds, "Array", "string"); + const serializedParams = ObjectSerializer.serialize(fieldIds, "Array", ""); for (const serializedParam of serializedParams) { requestContext.appendQueryParam("fieldIds", serializedParam); } @@ -75,7 +60,7 @@ export class CompaniesApiRequestFactory extends BaseAPIRequestFactory { // Query Params if (fieldTypes !== undefined) { - const serializedParams = ObjectSerializer.serialize(fieldTypes, "Array<'enriched' | 'global' | 'relationship-intelligence'>", "string"); + const serializedParams = ObjectSerializer.serialize(fieldTypes, "Array<'enriched' | 'global' | 'relationship-intelligence'>", ""); for (const serializedParam of serializedParams) { requestContext.appendQueryParam("fieldTypes", serializedParam); } @@ -98,18 +83,26 @@ export class CompaniesApiRequestFactory extends BaseAPIRequestFactory { } /** - * Returns metadata on non-list-specific Company Fields. Use the returned Field IDs to request field data from the GET `/v2/companies` and GET `/v2/companies/{id}` endpoints. - * Get metadata on Company Fields + * Paginate through the List Entries (AKA rows) for the given Company across all Lists. Each List Entry includes field data for the Company, including list-specific field data. Each List Entry also includes metadata about its creation, i.e., when it was added to the List and by whom. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Get a Company\'s List Entries + * @param companyId Company ID * @param cursor Cursor for the next or previous page * @param limit Number of items to include in the page */ - public async getV2CompaniesFields(cursor?: string, limit?: number, _options?: Configuration): Promise { + public async v2CompaniesCompanyIdListEntriesGET(companyId: number, cursor?: string, limit?: number, _options?: Configuration): Promise { let _config = _options || this.configuration; + // verify required parameter 'companyId' is not null or undefined + if (companyId === null || companyId === undefined) { + throw new RequiredError("CompaniesApi", "v2CompaniesCompanyIdListEntriesGET", "companyId"); + } + + // Path Params - const localVarPath = '/v2/companies/fields'; + const localVarPath = '/v2/companies/{companyId}/list-entries' + .replace('{' + 'companyId' + '}', encodeURIComponent(String(companyId))); // Make Request Context const requestContext = _config.baseServer.makeRequestContext(localVarPath, HttpMethod.GET); @@ -142,45 +135,39 @@ export class CompaniesApiRequestFactory extends BaseAPIRequestFactory { } /** - * Returns basic information and non-list-specific field data on the requested Company. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/companies/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Companies will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All Organizations directory\" [permission](#section/Getting-Started/Permissions). - * Get a single Company - * @param id Company ID - * @param fieldIds Field IDs for which to return field data - * @param fieldTypes Field Types for which to return field data + * Paginate through all Lists where the given Company appears as an entry and that you have access to view. Returns basic List information for each List that contains this Company. + * Get a Company\'s Lists + * @param companyId Company ID + * @param cursor Cursor for the next or previous page + * @param limit Number of items to include in the page */ - public async getV2CompaniesId(id: number, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: Configuration): Promise { + public async v2CompaniesCompanyIdListsGET(companyId: number, cursor?: string, limit?: number, _options?: Configuration): Promise { let _config = _options || this.configuration; - // verify required parameter 'id' is not null or undefined - if (id === null || id === undefined) { - throw new RequiredError("CompaniesApi", "getV2CompaniesId", "id"); + // verify required parameter 'companyId' is not null or undefined + if (companyId === null || companyId === undefined) { + throw new RequiredError("CompaniesApi", "v2CompaniesCompanyIdListsGET", "companyId"); } // Path Params - const localVarPath = '/v2/companies/{id}' - .replace('{' + 'id' + '}', encodeURIComponent(String(id))); + const localVarPath = '/v2/companies/{companyId}/lists' + .replace('{' + 'companyId' + '}', encodeURIComponent(String(companyId))); // Make Request Context const requestContext = _config.baseServer.makeRequestContext(localVarPath, HttpMethod.GET); requestContext.setHeaderParam("Accept", "application/json, */*;q=0.8") // Query Params - if (fieldIds !== undefined) { - const serializedParams = ObjectSerializer.serialize(fieldIds, "Array", "string"); - for (const serializedParam of serializedParams) { - requestContext.appendQueryParam("fieldIds", serializedParam); - } + if (cursor !== undefined) { + requestContext.setQueryParam("cursor", ObjectSerializer.serialize(cursor, "string", "")); } // Query Params - if (fieldTypes !== undefined) { - const serializedParams = ObjectSerializer.serialize(fieldTypes, "Array<'enriched' | 'global' | 'relationship-intelligence'>", "string"); - for (const serializedParam of serializedParams) { - requestContext.appendQueryParam("fieldTypes", serializedParam); - } + if (limit !== undefined) { + requestContext.setQueryParam("limit", ObjectSerializer.serialize(limit, "number", "int32")); } @@ -200,31 +187,40 @@ export class CompaniesApiRequestFactory extends BaseAPIRequestFactory { } /** - * Paginate through the List Entries (AKA rows) for the given Company across all Lists. Each List Entry includes field data for the Company, including list-specific field data. Each List Entry also includes metadata about its creation, i.e., when it was added to the List and by whom. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Get a Company\'s List Entries - * @param id Company ID + * | ⚠️ This endpoint is currently in BETA | |--| Returns relevant notes for a given company which includes directly attached notes and notes attached to persons on this company. You can filter notes using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|---------------------------------| | `creator.id` | Filter notes by the creator of the note | `int32` | `=` | `creator.id=1` | | `createdAt` | Filter notes by when it was created | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-02-04T10:48:24Z` | | `updatedAt` | Filter notes by when it was updated | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-02-03T10:48:24Z`| + * Get Notes for a Company + * @param companyId Company\'s ID + * @param filter Filter options * @param cursor Cursor for the next or previous page * @param limit Number of items to include in the page + * @param totalCount Include total count of the collection in the pagination response */ - public async getV2CompaniesIdListEntries(id: number, cursor?: string, limit?: number, _options?: Configuration): Promise { + public async v2CompaniesCompanyIdNotesGET(companyId: number, filter?: string, cursor?: string, limit?: number, totalCount?: boolean, _options?: Configuration): Promise { let _config = _options || this.configuration; - // verify required parameter 'id' is not null or undefined - if (id === null || id === undefined) { - throw new RequiredError("CompaniesApi", "getV2CompaniesIdListEntries", "id"); + // verify required parameter 'companyId' is not null or undefined + if (companyId === null || companyId === undefined) { + throw new RequiredError("CompaniesApi", "v2CompaniesCompanyIdNotesGET", "companyId"); } + + // Path Params - const localVarPath = '/v2/companies/{id}/list-entries' - .replace('{' + 'id' + '}', encodeURIComponent(String(id))); + const localVarPath = '/v2/companies/{companyId}/notes' + .replace('{' + 'companyId' + '}', encodeURIComponent(String(companyId))); // Make Request Context const requestContext = _config.baseServer.makeRequestContext(localVarPath, HttpMethod.GET); requestContext.setHeaderParam("Accept", "application/json, */*;q=0.8") + // Query Params + if (filter !== undefined) { + requestContext.setQueryParam("filter", ObjectSerializer.serialize(filter, "string", "")); + } + // Query Params if (cursor !== undefined) { requestContext.setQueryParam("cursor", ObjectSerializer.serialize(cursor, "string", "")); @@ -235,6 +231,11 @@ export class CompaniesApiRequestFactory extends BaseAPIRequestFactory { requestContext.setQueryParam("limit", ObjectSerializer.serialize(limit, "number", "int32")); } + // Query Params + if (totalCount !== undefined) { + requestContext.setQueryParam("totalCount", ObjectSerializer.serialize(totalCount, "boolean", "")); + } + let authMethod: SecurityAuthentication | undefined; // Apply auth methods @@ -252,26 +253,68 @@ export class CompaniesApiRequestFactory extends BaseAPIRequestFactory { } /** - * Returns metadata for all the Lists on which the given Company appears. - * Get a Company\'s Lists - * @param id Company ID + * Returns metadata on non-list-specific Company Fields. Use the returned Field IDs to request field data from the GET `/v2/companies` and GET `/v2/companies/{id}` endpoints. + * Get metadata on Company Fields * @param cursor Cursor for the next or previous page * @param limit Number of items to include in the page */ - public async getV2CompaniesIdLists(id: number, cursor?: string, limit?: number, _options?: Configuration): Promise { + public async v2CompaniesFieldsGET(cursor?: string, limit?: number, _options?: Configuration): Promise { let _config = _options || this.configuration; - // verify required parameter 'id' is not null or undefined - if (id === null || id === undefined) { - throw new RequiredError("CompaniesApi", "getV2CompaniesIdLists", "id"); + + + // Path Params + const localVarPath = '/v2/companies/fields'; + + // Make Request Context + const requestContext = _config.baseServer.makeRequestContext(localVarPath, HttpMethod.GET); + requestContext.setHeaderParam("Accept", "application/json, */*;q=0.8") + + // Query Params + if (cursor !== undefined) { + requestContext.setQueryParam("cursor", ObjectSerializer.serialize(cursor, "string", "")); + } + + // Query Params + if (limit !== undefined) { + requestContext.setQueryParam("limit", ObjectSerializer.serialize(limit, "number", "int32")); + } + + + let authMethod: SecurityAuthentication | undefined; + // Apply auth methods + authMethod = _config.authMethods["bearerAuth"] + if (authMethod?.applySecurityAuthentication) { + await authMethod?.applySecurityAuthentication(requestContext); } + + const defaultAuth: SecurityAuthentication | undefined = _config?.authMethods?.default + if (defaultAuth?.applySecurityAuthentication) { + await defaultAuth?.applySecurityAuthentication(requestContext); + } + + return requestContext; + } + + /** + * Paginate through Companies in Affinity. Returns basic information and non-list-specific field data on each Company. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/companies/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Companies will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All Organizations directory\" [permission](#section/Getting-Started/Permissions). + * Get all Companies + * @param cursor Cursor for the next or previous page + * @param limit Number of items to include in the page + * @param ids Company IDs + * @param fieldIds Field IDs for which to return field data + * @param fieldTypes Field Types for which to return field data + */ + public async v2CompaniesGET(cursor?: string, limit?: number, ids?: Array, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: Configuration): Promise { + let _config = _options || this.configuration; + + // Path Params - const localVarPath = '/v2/companies/{id}/lists' - .replace('{' + 'id' + '}', encodeURIComponent(String(id))); + const localVarPath = '/v2/companies'; // Make Request Context const requestContext = _config.baseServer.makeRequestContext(localVarPath, HttpMethod.GET); @@ -287,6 +330,30 @@ export class CompaniesApiRequestFactory extends BaseAPIRequestFactory { requestContext.setQueryParam("limit", ObjectSerializer.serialize(limit, "number", "int32")); } + // Query Params + if (ids !== undefined) { + const serializedParams = ObjectSerializer.serialize(ids, "Array", "int64"); + for (const serializedParam of serializedParams) { + requestContext.appendQueryParam("ids", serializedParam); + } + } + + // Query Params + if (fieldIds !== undefined) { + const serializedParams = ObjectSerializer.serialize(fieldIds, "Array", ""); + for (const serializedParam of serializedParams) { + requestContext.appendQueryParam("fieldIds", serializedParam); + } + } + + // Query Params + if (fieldTypes !== undefined) { + const serializedParams = ObjectSerializer.serialize(fieldTypes, "Array<'enriched' | 'global' | 'relationship-intelligence'>", ""); + for (const serializedParam of serializedParams) { + requestContext.appendQueryParam("fieldTypes", serializedParam); + } + } + let authMethod: SecurityAuthentication | undefined; // Apply auth methods @@ -311,24 +378,24 @@ export class CompaniesApiResponseProcessor { * Unwraps the actual response sent by the server from the response context and deserializes the response content * to the expected objects * - * @params response Response returned by the server for a request to getV2Companies + * @params response Response returned by the server for a request to v2CompaniesCompanyIdGET * @throws ApiException if the response code was not in [200, 299] */ - public async getV2CompaniesWithHttpInfo(response: ResponseContext): Promise> { + public async v2CompaniesCompanyIdGETWithHttpInfo(response: ResponseContext): Promise> { const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); if (isCodeInRange("200", response.httpStatusCode)) { - const body: CompanyPaged = ObjectSerializer.deserialize( + const body: Company = ObjectSerializer.deserialize( ObjectSerializer.parse(await response.body.text(), contentType), - "CompanyPaged", "" - ) as CompanyPaged; + "Company", "" + ) as Company; return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); } if (isCodeInRange("400", response.httpStatusCode)) { - const body: InlineObject = ObjectSerializer.deserialize( + const body: Responses400 = ObjectSerializer.deserialize( ObjectSerializer.parse(await response.body.text(), contentType), - "InlineObject", "" - ) as InlineObject; - throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); } if (isCodeInRange("403", response.httpStatusCode)) { const body: AuthorizationErrors = ObjectSerializer.deserialize( @@ -337,6 +404,13 @@ export class CompaniesApiResponseProcessor { ) as AuthorizationErrors; throw new ApiException(response.httpStatusCode, "Forbidden", body, response.headers); } + if (isCodeInRange("404", response.httpStatusCode)) { + const body: NotFoundErrors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "NotFoundErrors", "" + ) as NotFoundErrors; + throw new ApiException(response.httpStatusCode, "Not Found", body, response.headers); + } if (isCodeInRange("0", response.httpStatusCode)) { const body: Errors = ObjectSerializer.deserialize( ObjectSerializer.parse(await response.body.text(), contentType), @@ -347,10 +421,10 @@ export class CompaniesApiResponseProcessor { // Work around for missing responses in specification, e.g. for petstore.yaml if (response.httpStatusCode >= 200 && response.httpStatusCode <= 299) { - const body: CompanyPaged = ObjectSerializer.deserialize( + const body: Company = ObjectSerializer.deserialize( ObjectSerializer.parse(await response.body.text(), contentType), - "CompanyPaged", "" - ) as CompanyPaged; + "Company", "" + ) as Company; return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); } @@ -361,24 +435,38 @@ export class CompaniesApiResponseProcessor { * Unwraps the actual response sent by the server from the response context and deserializes the response content * to the expected objects * - * @params response Response returned by the server for a request to getV2CompaniesFields + * @params response Response returned by the server for a request to v2CompaniesCompanyIdListEntriesGET * @throws ApiException if the response code was not in [200, 299] */ - public async getV2CompaniesFieldsWithHttpInfo(response: ResponseContext): Promise> { + public async v2CompaniesCompanyIdListEntriesGETWithHttpInfo(response: ResponseContext): Promise> { const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); if (isCodeInRange("200", response.httpStatusCode)) { - const body: FieldMetadataPaged = ObjectSerializer.deserialize( + const body: ListEntryPaged = ObjectSerializer.deserialize( ObjectSerializer.parse(await response.body.text(), contentType), - "FieldMetadataPaged", "" - ) as FieldMetadataPaged; + "ListEntryPaged", "" + ) as ListEntryPaged; return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); } if (isCodeInRange("400", response.httpStatusCode)) { - const body: InlineObject = ObjectSerializer.deserialize( + const body: Responses400 = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + } + if (isCodeInRange("403", response.httpStatusCode)) { + const body: AuthorizationErrors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "AuthorizationErrors", "" + ) as AuthorizationErrors; + throw new ApiException(response.httpStatusCode, "Forbidden", body, response.headers); + } + if (isCodeInRange("404", response.httpStatusCode)) { + const body: NotFoundErrors = ObjectSerializer.deserialize( ObjectSerializer.parse(await response.body.text(), contentType), - "InlineObject", "" - ) as InlineObject; - throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + "NotFoundErrors", "" + ) as NotFoundErrors; + throw new ApiException(response.httpStatusCode, "Not Found", body, response.headers); } if (isCodeInRange("0", response.httpStatusCode)) { const body: Errors = ObjectSerializer.deserialize( @@ -390,10 +478,10 @@ export class CompaniesApiResponseProcessor { // Work around for missing responses in specification, e.g. for petstore.yaml if (response.httpStatusCode >= 200 && response.httpStatusCode <= 299) { - const body: FieldMetadataPaged = ObjectSerializer.deserialize( + const body: ListEntryPaged = ObjectSerializer.deserialize( ObjectSerializer.parse(await response.body.text(), contentType), - "FieldMetadataPaged", "" - ) as FieldMetadataPaged; + "ListEntryPaged", "" + ) as ListEntryPaged; return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); } @@ -404,31 +492,24 @@ export class CompaniesApiResponseProcessor { * Unwraps the actual response sent by the server from the response context and deserializes the response content * to the expected objects * - * @params response Response returned by the server for a request to getV2CompaniesId + * @params response Response returned by the server for a request to v2CompaniesCompanyIdListsGET * @throws ApiException if the response code was not in [200, 299] */ - public async getV2CompaniesIdWithHttpInfo(response: ResponseContext): Promise> { + public async v2CompaniesCompanyIdListsGETWithHttpInfo(response: ResponseContext): Promise> { const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); if (isCodeInRange("200", response.httpStatusCode)) { - const body: Company = ObjectSerializer.deserialize( + const body: ListPaged = ObjectSerializer.deserialize( ObjectSerializer.parse(await response.body.text(), contentType), - "Company", "" - ) as Company; + "ListPaged", "" + ) as ListPaged; return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); } if (isCodeInRange("400", response.httpStatusCode)) { - const body: InlineObject = ObjectSerializer.deserialize( + const body: Responses400 = ObjectSerializer.deserialize( ObjectSerializer.parse(await response.body.text(), contentType), - "InlineObject", "" - ) as InlineObject; - throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); - } - if (isCodeInRange("403", response.httpStatusCode)) { - const body: AuthorizationErrors = ObjectSerializer.deserialize( - ObjectSerializer.parse(await response.body.text(), contentType), - "AuthorizationErrors", "" - ) as AuthorizationErrors; - throw new ApiException(response.httpStatusCode, "Forbidden", body, response.headers); + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); } if (isCodeInRange("404", response.httpStatusCode)) { const body: NotFoundErrors = ObjectSerializer.deserialize( @@ -447,10 +528,10 @@ export class CompaniesApiResponseProcessor { // Work around for missing responses in specification, e.g. for petstore.yaml if (response.httpStatusCode >= 200 && response.httpStatusCode <= 299) { - const body: Company = ObjectSerializer.deserialize( + const body: ListPaged = ObjectSerializer.deserialize( ObjectSerializer.parse(await response.body.text(), contentType), - "Company", "" - ) as Company; + "ListPaged", "" + ) as ListPaged; return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); } @@ -461,31 +542,24 @@ export class CompaniesApiResponseProcessor { * Unwraps the actual response sent by the server from the response context and deserializes the response content * to the expected objects * - * @params response Response returned by the server for a request to getV2CompaniesIdListEntries + * @params response Response returned by the server for a request to v2CompaniesCompanyIdNotesGET * @throws ApiException if the response code was not in [200, 299] */ - public async getV2CompaniesIdListEntriesWithHttpInfo(response: ResponseContext): Promise> { + public async v2CompaniesCompanyIdNotesGETWithHttpInfo(response: ResponseContext): Promise> { const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); if (isCodeInRange("200", response.httpStatusCode)) { - const body: ListEntryPaged = ObjectSerializer.deserialize( + const body: NotesNotesPaged = ObjectSerializer.deserialize( ObjectSerializer.parse(await response.body.text(), contentType), - "ListEntryPaged", "" - ) as ListEntryPaged; + "NotesNotesPaged", "" + ) as NotesNotesPaged; return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); } if (isCodeInRange("400", response.httpStatusCode)) { - const body: InlineObject = ObjectSerializer.deserialize( - ObjectSerializer.parse(await response.body.text(), contentType), - "InlineObject", "" - ) as InlineObject; - throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); - } - if (isCodeInRange("403", response.httpStatusCode)) { - const body: AuthorizationErrors = ObjectSerializer.deserialize( + const body: Responses400 = ObjectSerializer.deserialize( ObjectSerializer.parse(await response.body.text(), contentType), - "AuthorizationErrors", "" - ) as AuthorizationErrors; - throw new ApiException(response.httpStatusCode, "Forbidden", body, response.headers); + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); } if (isCodeInRange("404", response.httpStatusCode)) { const body: NotFoundErrors = ObjectSerializer.deserialize( @@ -504,10 +578,10 @@ export class CompaniesApiResponseProcessor { // Work around for missing responses in specification, e.g. for petstore.yaml if (response.httpStatusCode >= 200 && response.httpStatusCode <= 299) { - const body: ListEntryPaged = ObjectSerializer.deserialize( + const body: NotesNotesPaged = ObjectSerializer.deserialize( ObjectSerializer.parse(await response.body.text(), contentType), - "ListEntryPaged", "" - ) as ListEntryPaged; + "NotesNotesPaged", "" + ) as NotesNotesPaged; return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); } @@ -518,31 +592,74 @@ export class CompaniesApiResponseProcessor { * Unwraps the actual response sent by the server from the response context and deserializes the response content * to the expected objects * - * @params response Response returned by the server for a request to getV2CompaniesIdLists + * @params response Response returned by the server for a request to v2CompaniesFieldsGET * @throws ApiException if the response code was not in [200, 299] */ - public async getV2CompaniesIdListsWithHttpInfo(response: ResponseContext): Promise> { + public async v2CompaniesFieldsGETWithHttpInfo(response: ResponseContext): Promise> { const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); if (isCodeInRange("200", response.httpStatusCode)) { - const body: ListPaged = ObjectSerializer.deserialize( + const body: FieldMetadataPaged = ObjectSerializer.deserialize( ObjectSerializer.parse(await response.body.text(), contentType), - "ListPaged", "" - ) as ListPaged; + "FieldMetadataPaged", "" + ) as FieldMetadataPaged; return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); } if (isCodeInRange("400", response.httpStatusCode)) { - const body: InlineObject = ObjectSerializer.deserialize( + const body: Responses400 = ObjectSerializer.deserialize( ObjectSerializer.parse(await response.body.text(), contentType), - "InlineObject", "" - ) as InlineObject; - throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); } - if (isCodeInRange("404", response.httpStatusCode)) { - const body: NotFoundErrors = ObjectSerializer.deserialize( + if (isCodeInRange("0", response.httpStatusCode)) { + const body: Errors = ObjectSerializer.deserialize( ObjectSerializer.parse(await response.body.text(), contentType), - "NotFoundErrors", "" - ) as NotFoundErrors; - throw new ApiException(response.httpStatusCode, "Not Found", body, response.headers); + "Errors", "" + ) as Errors; + throw new ApiException(response.httpStatusCode, "Errors", body, response.headers); + } + + // Work around for missing responses in specification, e.g. for petstore.yaml + if (response.httpStatusCode >= 200 && response.httpStatusCode <= 299) { + const body: FieldMetadataPaged = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "FieldMetadataPaged", "" + ) as FieldMetadataPaged; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + + throw new ApiException(response.httpStatusCode, "Unknown API Status Code!", await response.getBodyAsAny(), response.headers); + } + + /** + * Unwraps the actual response sent by the server from the response context and deserializes the response content + * to the expected objects + * + * @params response Response returned by the server for a request to v2CompaniesGET + * @throws ApiException if the response code was not in [200, 299] + */ + public async v2CompaniesGETWithHttpInfo(response: ResponseContext): Promise> { + const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); + if (isCodeInRange("200", response.httpStatusCode)) { + const body: CompanyPaged = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "CompanyPaged", "" + ) as CompanyPaged; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + if (isCodeInRange("400", response.httpStatusCode)) { + const body: Responses400 = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + } + if (isCodeInRange("403", response.httpStatusCode)) { + const body: AuthorizationErrors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "AuthorizationErrors", "" + ) as AuthorizationErrors; + throw new ApiException(response.httpStatusCode, "Forbidden", body, response.headers); } if (isCodeInRange("0", response.httpStatusCode)) { const body: Errors = ObjectSerializer.deserialize( @@ -554,10 +671,10 @@ export class CompaniesApiResponseProcessor { // Work around for missing responses in specification, e.g. for petstore.yaml if (response.httpStatusCode >= 200 && response.httpStatusCode <= 299) { - const body: ListPaged = ObjectSerializer.deserialize( + const body: CompanyPaged = ObjectSerializer.deserialize( ObjectSerializer.parse(await response.body.text(), contentType), - "ListPaged", "" - ) as ListPaged; + "CompanyPaged", "" + ) as CompanyPaged; return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); } diff --git a/src/v2/generated/apis/CompanyMergesApi.ts b/src/v2/generated/apis/CompanyMergesApi.ts new file mode 100644 index 0000000..0b66fc6 --- /dev/null +++ b/src/v2/generated/apis/CompanyMergesApi.ts @@ -0,0 +1,521 @@ +// TODO: better import syntax? +import {BaseAPIRequestFactory, RequiredError, COLLECTION_FORMATS} from './baseapi.ts'; +import {Configuration} from '../configuration.ts'; +import {RequestContext, HttpMethod, ResponseContext, HttpFile, HttpInfo} from '../http/http.ts'; +import {ObjectSerializer} from '../models/ObjectSerializer.ts'; +import {ApiException} from './exception.ts'; +import {canConsumeForm, isCodeInRange} from '../util.ts'; +import {SecurityAuthentication} from '../auth/auth.ts'; + + +import { AuthorizationErrors } from '../models/AuthorizationErrors.ts'; +import { CompanyMergeRequest } from '../models/CompanyMergeRequest.ts'; +import { CompanyMergeResponse } from '../models/CompanyMergeResponse.ts'; +import { CompanyMergeState } from '../models/CompanyMergeState.ts'; +import { CompanyMergeStatePaged } from '../models/CompanyMergeStatePaged.ts'; +import { CompanyMergeTask } from '../models/CompanyMergeTask.ts'; +import { CompanyMergeTaskPaged } from '../models/CompanyMergeTaskPaged.ts'; +import { Errors } from '../models/Errors.ts'; +import { NotFoundErrors } from '../models/NotFoundErrors.ts'; +import { Responses400 } from '../models/Responses400.ts'; + +/** + * no description + */ +export class CompanyMergesApiRequestFactory extends BaseAPIRequestFactory { + + /** + * Retrieve paginated company merges for the organization. Returns all company merges initiated by users in your organization, including their current status, the companies involved, and merge details. You can filter company merges using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties: | Property | Type | Operators | Values | Examples | |----------|------|-----------|--------|----------| | `status` | `enum` | `=` | `in-progress`, `success`, `failed` | `status=failed` | | `taskId` | `string` | `=` | | `taskId=789e0123-e45b-67c8-d901-234567890123` | Company merges are returned in reverse chronological order (most recent first). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get All Company Merges + * @param cursor Cursor for the next or previous page + * @param limit Number of items to include in the page + * @param filter Filter company merges using Affinity Filtering Language + */ + public async v2CompanyMergesGET(cursor?: string, limit?: number, filter?: string, _options?: Configuration): Promise { + let _config = _options || this.configuration; + + + + + // Path Params + const localVarPath = '/v2/company-merges'; + + // Make Request Context + const requestContext = _config.baseServer.makeRequestContext(localVarPath, HttpMethod.GET); + requestContext.setHeaderParam("Accept", "application/json, */*;q=0.8") + + // Query Params + if (cursor !== undefined) { + requestContext.setQueryParam("cursor", ObjectSerializer.serialize(cursor, "string", "")); + } + + // Query Params + if (limit !== undefined) { + requestContext.setQueryParam("limit", ObjectSerializer.serialize(limit, "number", "int32")); + } + + // Query Params + if (filter !== undefined) { + requestContext.setQueryParam("filter", ObjectSerializer.serialize(filter, "string", "")); + } + + + let authMethod: SecurityAuthentication | undefined; + // Apply auth methods + authMethod = _config.authMethods["bearerAuth"] + if (authMethod?.applySecurityAuthentication) { + await authMethod?.applySecurityAuthentication(requestContext); + } + + const defaultAuth: SecurityAuthentication | undefined = _config?.authMethods?.default + if (defaultAuth?.applySecurityAuthentication) { + await defaultAuth?.applySecurityAuthentication(requestContext); + } + + return requestContext; + } + + /** + * Retrieve the status and details of a specific company merge. Returns information about the company merge including its current status, the companies involved, timestamps, and any error information if the merge failed. The `mergeId` can be obtained from the response of the [Get All Company Merges](#tag/companyMerges/operation/v2_company-merges__GET) endpoint, or by filtering company merges by task ID using `/v2/company-merges?filter=taskId={taskId}` after initiating a merge. Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get Company Merge + * @param mergeId Company merge ID + */ + public async v2CompanyMergesMergeIdGET(mergeId: number, _options?: Configuration): Promise { + let _config = _options || this.configuration; + + // verify required parameter 'mergeId' is not null or undefined + if (mergeId === null || mergeId === undefined) { + throw new RequiredError("CompanyMergesApi", "v2CompanyMergesMergeIdGET", "mergeId"); + } + + + // Path Params + const localVarPath = '/v2/company-merges/{mergeId}' + .replace('{' + 'mergeId' + '}', encodeURIComponent(String(mergeId))); + + // Make Request Context + const requestContext = _config.baseServer.makeRequestContext(localVarPath, HttpMethod.GET); + requestContext.setHeaderParam("Accept", "application/json, */*;q=0.8") + + + let authMethod: SecurityAuthentication | undefined; + // Apply auth methods + authMethod = _config.authMethods["bearerAuth"] + if (authMethod?.applySecurityAuthentication) { + await authMethod?.applySecurityAuthentication(requestContext); + } + + const defaultAuth: SecurityAuthentication | undefined = _config?.authMethods?.default + if (defaultAuth?.applySecurityAuthentication) { + await defaultAuth?.applySecurityAuthentication(requestContext); + } + + return requestContext; + } + + /** + * Initiate a company merge to combine a duplicate company profile into a primary company profile. This is an asynchronous process that will merge all data from the duplicate company into the primary company. Once the merge is initiated, you can track its progress using the returned [task URL](#tag/companyMerges/operation/v2_tasks_company-merges_taskId__GET). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Initiate Company Merge + * @param companyMergeRequest + */ + public async v2CompanyMergesPOST(companyMergeRequest: CompanyMergeRequest, _options?: Configuration): Promise { + let _config = _options || this.configuration; + + // verify required parameter 'companyMergeRequest' is not null or undefined + if (companyMergeRequest === null || companyMergeRequest === undefined) { + throw new RequiredError("CompanyMergesApi", "v2CompanyMergesPOST", "companyMergeRequest"); + } + + + // Path Params + const localVarPath = '/v2/company-merges'; + + // Make Request Context + const requestContext = _config.baseServer.makeRequestContext(localVarPath, HttpMethod.POST); + requestContext.setHeaderParam("Accept", "application/json, */*;q=0.8") + + + // Body Params + const contentType = ObjectSerializer.getPreferredMediaType([ + "application/json" + ]); + requestContext.setHeaderParam("Content-Type", contentType); + const serializedBody = ObjectSerializer.stringify( + ObjectSerializer.serialize(companyMergeRequest, "CompanyMergeRequest", ""), + contentType + ); + requestContext.setBody(serializedBody); + + let authMethod: SecurityAuthentication | undefined; + // Apply auth methods + authMethod = _config.authMethods["bearerAuth"] + if (authMethod?.applySecurityAuthentication) { + await authMethod?.applySecurityAuthentication(requestContext); + } + + const defaultAuth: SecurityAuthentication | undefined = _config?.authMethods?.default + if (defaultAuth?.applySecurityAuthentication) { + await defaultAuth?.applySecurityAuthentication(requestContext); + } + + return requestContext; + } + + /** + * Retrieve paginated company merge tasks for the organization. Returns all merge tasks initiated by users in your organization, including their current status, the companies involved, and task details. You can filter tasks using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties: | Property | Type | Operators | Values | Examples | |----------|------|-----------|--------|----------| | `status` | `enum` | `=` | `in-progress`, `success`, `failed` | `status=failed` | Tasks are returned in reverse chronological order (most recent first). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get All Company Merge Tasks + * @param cursor Cursor for the next or previous page + * @param limit Number of items to include in the page + * @param filter Filter tasks using Affinity Filtering Language + */ + public async v2TasksCompanyMergesGET(cursor?: string, limit?: number, filter?: string, _options?: Configuration): Promise { + let _config = _options || this.configuration; + + + + + // Path Params + const localVarPath = '/v2/tasks/company-merges'; + + // Make Request Context + const requestContext = _config.baseServer.makeRequestContext(localVarPath, HttpMethod.GET); + requestContext.setHeaderParam("Accept", "application/json, */*;q=0.8") + + // Query Params + if (cursor !== undefined) { + requestContext.setQueryParam("cursor", ObjectSerializer.serialize(cursor, "string", "")); + } + + // Query Params + if (limit !== undefined) { + requestContext.setQueryParam("limit", ObjectSerializer.serialize(limit, "number", "int32")); + } + + // Query Params + if (filter !== undefined) { + requestContext.setQueryParam("filter", ObjectSerializer.serialize(filter, "string", "")); + } + + + let authMethod: SecurityAuthentication | undefined; + // Apply auth methods + authMethod = _config.authMethods["bearerAuth"] + if (authMethod?.applySecurityAuthentication) { + await authMethod?.applySecurityAuthentication(requestContext); + } + + const defaultAuth: SecurityAuthentication | undefined = _config?.authMethods?.default + if (defaultAuth?.applySecurityAuthentication) { + await defaultAuth?.applySecurityAuthentication(requestContext); + } + + return requestContext; + } + + /** + * Retrieve the status and details of a specific task for company merges. Returns information about the company merges for a specific task including its overall status, number of merges in-progress, completed, and failed. Detailed information about individual merges for this task can be found by querying: `/v2/company-merges?filter=taskId={taskId}` See [Company Merges](#tag/companyMerges/operation/v2_company-merges__GET) for more details. Task statuses: - `in-progress`: The merge task is currently being processed. - `success`: The merge task completed successfully. - `failed`: The merge task failed. Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get Company Merge Task + * @param taskId Company merge task ID + */ + public async v2TasksCompanyMergesTaskIdGET(taskId: string, _options?: Configuration): Promise { + let _config = _options || this.configuration; + + // verify required parameter 'taskId' is not null or undefined + if (taskId === null || taskId === undefined) { + throw new RequiredError("CompanyMergesApi", "v2TasksCompanyMergesTaskIdGET", "taskId"); + } + + + // Path Params + const localVarPath = '/v2/tasks/company-merges/{taskId}' + .replace('{' + 'taskId' + '}', encodeURIComponent(String(taskId))); + + // Make Request Context + const requestContext = _config.baseServer.makeRequestContext(localVarPath, HttpMethod.GET); + requestContext.setHeaderParam("Accept", "application/json, */*;q=0.8") + + + let authMethod: SecurityAuthentication | undefined; + // Apply auth methods + authMethod = _config.authMethods["bearerAuth"] + if (authMethod?.applySecurityAuthentication) { + await authMethod?.applySecurityAuthentication(requestContext); + } + + const defaultAuth: SecurityAuthentication | undefined = _config?.authMethods?.default + if (defaultAuth?.applySecurityAuthentication) { + await defaultAuth?.applySecurityAuthentication(requestContext); + } + + return requestContext; + } + +} + +export class CompanyMergesApiResponseProcessor { + + /** + * Unwraps the actual response sent by the server from the response context and deserializes the response content + * to the expected objects + * + * @params response Response returned by the server for a request to v2CompanyMergesGET + * @throws ApiException if the response code was not in [200, 299] + */ + public async v2CompanyMergesGETWithHttpInfo(response: ResponseContext): Promise> { + const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); + if (isCodeInRange("200", response.httpStatusCode)) { + const body: CompanyMergeStatePaged = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "CompanyMergeStatePaged", "" + ) as CompanyMergeStatePaged; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + if (isCodeInRange("400", response.httpStatusCode)) { + const body: Responses400 = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + } + if (isCodeInRange("403", response.httpStatusCode)) { + const body: AuthorizationErrors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "AuthorizationErrors", "" + ) as AuthorizationErrors; + throw new ApiException(response.httpStatusCode, "Forbidden", body, response.headers); + } + if (isCodeInRange("0", response.httpStatusCode)) { + const body: Errors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Errors", "" + ) as Errors; + throw new ApiException(response.httpStatusCode, "Errors", body, response.headers); + } + + // Work around for missing responses in specification, e.g. for petstore.yaml + if (response.httpStatusCode >= 200 && response.httpStatusCode <= 299) { + const body: CompanyMergeStatePaged = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "CompanyMergeStatePaged", "" + ) as CompanyMergeStatePaged; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + + throw new ApiException(response.httpStatusCode, "Unknown API Status Code!", await response.getBodyAsAny(), response.headers); + } + + /** + * Unwraps the actual response sent by the server from the response context and deserializes the response content + * to the expected objects + * + * @params response Response returned by the server for a request to v2CompanyMergesMergeIdGET + * @throws ApiException if the response code was not in [200, 299] + */ + public async v2CompanyMergesMergeIdGETWithHttpInfo(response: ResponseContext): Promise> { + const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); + if (isCodeInRange("200", response.httpStatusCode)) { + const body: CompanyMergeState = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "CompanyMergeState", "" + ) as CompanyMergeState; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + if (isCodeInRange("400", response.httpStatusCode)) { + const body: Responses400 = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + } + if (isCodeInRange("403", response.httpStatusCode)) { + const body: AuthorizationErrors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "AuthorizationErrors", "" + ) as AuthorizationErrors; + throw new ApiException(response.httpStatusCode, "Forbidden", body, response.headers); + } + if (isCodeInRange("404", response.httpStatusCode)) { + const body: NotFoundErrors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "NotFoundErrors", "" + ) as NotFoundErrors; + throw new ApiException(response.httpStatusCode, "Not Found", body, response.headers); + } + if (isCodeInRange("0", response.httpStatusCode)) { + const body: Errors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Errors", "" + ) as Errors; + throw new ApiException(response.httpStatusCode, "Errors", body, response.headers); + } + + // Work around for missing responses in specification, e.g. for petstore.yaml + if (response.httpStatusCode >= 200 && response.httpStatusCode <= 299) { + const body: CompanyMergeState = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "CompanyMergeState", "" + ) as CompanyMergeState; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + + throw new ApiException(response.httpStatusCode, "Unknown API Status Code!", await response.getBodyAsAny(), response.headers); + } + + /** + * Unwraps the actual response sent by the server from the response context and deserializes the response content + * to the expected objects + * + * @params response Response returned by the server for a request to v2CompanyMergesPOST + * @throws ApiException if the response code was not in [200, 299] + */ + public async v2CompanyMergesPOSTWithHttpInfo(response: ResponseContext): Promise> { + const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); + if (isCodeInRange("202", response.httpStatusCode)) { + const body: CompanyMergeResponse = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "CompanyMergeResponse", "" + ) as CompanyMergeResponse; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + if (isCodeInRange("400", response.httpStatusCode)) { + const body: Responses400 = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + } + if (isCodeInRange("403", response.httpStatusCode)) { + const body: AuthorizationErrors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "AuthorizationErrors", "" + ) as AuthorizationErrors; + throw new ApiException(response.httpStatusCode, "Forbidden", body, response.headers); + } + if (isCodeInRange("0", response.httpStatusCode)) { + const body: Errors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Errors", "" + ) as Errors; + throw new ApiException(response.httpStatusCode, "Errors", body, response.headers); + } + + // Work around for missing responses in specification, e.g. for petstore.yaml + if (response.httpStatusCode >= 200 && response.httpStatusCode <= 299) { + const body: CompanyMergeResponse = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "CompanyMergeResponse", "" + ) as CompanyMergeResponse; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + + throw new ApiException(response.httpStatusCode, "Unknown API Status Code!", await response.getBodyAsAny(), response.headers); + } + + /** + * Unwraps the actual response sent by the server from the response context and deserializes the response content + * to the expected objects + * + * @params response Response returned by the server for a request to v2TasksCompanyMergesGET + * @throws ApiException if the response code was not in [200, 299] + */ + public async v2TasksCompanyMergesGETWithHttpInfo(response: ResponseContext): Promise> { + const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); + if (isCodeInRange("200", response.httpStatusCode)) { + const body: CompanyMergeTaskPaged = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "CompanyMergeTaskPaged", "" + ) as CompanyMergeTaskPaged; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + if (isCodeInRange("400", response.httpStatusCode)) { + const body: Responses400 = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + } + if (isCodeInRange("403", response.httpStatusCode)) { + const body: AuthorizationErrors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "AuthorizationErrors", "" + ) as AuthorizationErrors; + throw new ApiException(response.httpStatusCode, "Forbidden", body, response.headers); + } + if (isCodeInRange("0", response.httpStatusCode)) { + const body: Errors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Errors", "" + ) as Errors; + throw new ApiException(response.httpStatusCode, "Errors", body, response.headers); + } + + // Work around for missing responses in specification, e.g. for petstore.yaml + if (response.httpStatusCode >= 200 && response.httpStatusCode <= 299) { + const body: CompanyMergeTaskPaged = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "CompanyMergeTaskPaged", "" + ) as CompanyMergeTaskPaged; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + + throw new ApiException(response.httpStatusCode, "Unknown API Status Code!", await response.getBodyAsAny(), response.headers); + } + + /** + * Unwraps the actual response sent by the server from the response context and deserializes the response content + * to the expected objects + * + * @params response Response returned by the server for a request to v2TasksCompanyMergesTaskIdGET + * @throws ApiException if the response code was not in [200, 299] + */ + public async v2TasksCompanyMergesTaskIdGETWithHttpInfo(response: ResponseContext): Promise> { + const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); + if (isCodeInRange("200", response.httpStatusCode)) { + const body: CompanyMergeTask = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "CompanyMergeTask", "" + ) as CompanyMergeTask; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + if (isCodeInRange("400", response.httpStatusCode)) { + const body: Responses400 = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + } + if (isCodeInRange("403", response.httpStatusCode)) { + const body: AuthorizationErrors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "AuthorizationErrors", "" + ) as AuthorizationErrors; + throw new ApiException(response.httpStatusCode, "Forbidden", body, response.headers); + } + if (isCodeInRange("404", response.httpStatusCode)) { + const body: NotFoundErrors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "NotFoundErrors", "" + ) as NotFoundErrors; + throw new ApiException(response.httpStatusCode, "Not Found", body, response.headers); + } + if (isCodeInRange("0", response.httpStatusCode)) { + const body: Errors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Errors", "" + ) as Errors; + throw new ApiException(response.httpStatusCode, "Errors", body, response.headers); + } + + // Work around for missing responses in specification, e.g. for petstore.yaml + if (response.httpStatusCode >= 200 && response.httpStatusCode <= 299) { + const body: CompanyMergeTask = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "CompanyMergeTask", "" + ) as CompanyMergeTask; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + + throw new ApiException(response.httpStatusCode, "Unknown API Status Code!", await response.getBodyAsAny(), response.headers); + } + +} diff --git a/src/v2/generated/apis/EmailsApi.ts b/src/v2/generated/apis/EmailsApi.ts new file mode 100644 index 0000000..1c4610b --- /dev/null +++ b/src/v2/generated/apis/EmailsApi.ts @@ -0,0 +1,118 @@ +// TODO: better import syntax? +import {BaseAPIRequestFactory, RequiredError, COLLECTION_FORMATS} from './baseapi.ts'; +import {Configuration} from '../configuration.ts'; +import {RequestContext, HttpMethod, ResponseContext, HttpFile, HttpInfo} from '../http/http.ts'; +import {ObjectSerializer} from '../models/ObjectSerializer.ts'; +import {ApiException} from './exception.ts'; +import {canConsumeForm, isCodeInRange} from '../util.ts'; +import {SecurityAuthentication} from '../auth/auth.ts'; + + +import { Errors } from '../models/Errors.ts'; +import { InteractionsEmailPaged } from '../models/InteractionsEmailPaged.ts'; +import { Responses400 } from '../models/Responses400.ts'; + +/** + * no description + */ +export class EmailsApiRequestFactory extends BaseAPIRequestFactory { + + /** + * Paginate through all emails in Affinity. Returns basic information about the email interaction and its participants. Will only return emails or subject lines that the current authenticated user has permission to see. You can filter emails using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|----------------------------------| | `id` | Unique identifier for Emails | `int64` | `=` | `id=1` | | `sentAt` | When the Email was sent at | `datetime` | `>`, `<`, `>=`, `<=` | `sentAt>2025-01-01T01:00:00Z` | | `createdAt` | When the Email was created in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-01-01T01:00:00Z` | | `updatedAt` | When the Email was updated in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-01-01T01:00:00Z`| + * Get metadata on all Emails + * @param cursor Cursor for the next or previous page + * @param limit Number of items to include in the page + * @param filter Filter options + */ + public async v2EmailsGET(cursor?: string, limit?: number, filter?: string, _options?: Configuration): Promise { + let _config = _options || this.configuration; + + + + + // Path Params + const localVarPath = '/v2/emails'; + + // Make Request Context + const requestContext = _config.baseServer.makeRequestContext(localVarPath, HttpMethod.GET); + requestContext.setHeaderParam("Accept", "application/json, */*;q=0.8") + + // Query Params + if (cursor !== undefined) { + requestContext.setQueryParam("cursor", ObjectSerializer.serialize(cursor, "string", "")); + } + + // Query Params + if (limit !== undefined) { + requestContext.setQueryParam("limit", ObjectSerializer.serialize(limit, "number", "int32")); + } + + // Query Params + if (filter !== undefined) { + requestContext.setQueryParam("filter", ObjectSerializer.serialize(filter, "string", "")); + } + + + let authMethod: SecurityAuthentication | undefined; + // Apply auth methods + authMethod = _config.authMethods["bearerAuth"] + if (authMethod?.applySecurityAuthentication) { + await authMethod?.applySecurityAuthentication(requestContext); + } + + const defaultAuth: SecurityAuthentication | undefined = _config?.authMethods?.default + if (defaultAuth?.applySecurityAuthentication) { + await defaultAuth?.applySecurityAuthentication(requestContext); + } + + return requestContext; + } + +} + +export class EmailsApiResponseProcessor { + + /** + * Unwraps the actual response sent by the server from the response context and deserializes the response content + * to the expected objects + * + * @params response Response returned by the server for a request to v2EmailsGET + * @throws ApiException if the response code was not in [200, 299] + */ + public async v2EmailsGETWithHttpInfo(response: ResponseContext): Promise> { + const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); + if (isCodeInRange("200", response.httpStatusCode)) { + const body: InteractionsEmailPaged = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "InteractionsEmailPaged", "" + ) as InteractionsEmailPaged; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + if (isCodeInRange("400", response.httpStatusCode)) { + const body: Responses400 = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + } + if (isCodeInRange("0", response.httpStatusCode)) { + const body: Errors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Errors", "" + ) as Errors; + throw new ApiException(response.httpStatusCode, "Errors", body, response.headers); + } + + // Work around for missing responses in specification, e.g. for petstore.yaml + if (response.httpStatusCode >= 200 && response.httpStatusCode <= 299) { + const body: InteractionsEmailPaged = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "InteractionsEmailPaged", "" + ) as InteractionsEmailPaged; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + + throw new ApiException(response.httpStatusCode, "Unknown API Status Code!", await response.getBodyAsAny(), response.headers); + } + +} diff --git a/src/v2/generated/apis/ListsApi.ts b/src/v2/generated/apis/ListsApi.ts index af4afdf..29302ce 100644 --- a/src/v2/generated/apis/ListsApi.ts +++ b/src/v2/generated/apis/ListsApi.ts @@ -14,7 +14,6 @@ import { Field } from '../models/Field.ts'; import { FieldMetadataPaged } from '../models/FieldMetadataPaged.ts'; import { FieldPaged } from '../models/FieldPaged.ts'; import { FieldUpdate } from '../models/FieldUpdate.ts'; -import { InlineObject } from '../models/InlineObject.ts'; import { ListEntryBatchOperationResponse } from '../models/ListEntryBatchOperationResponse.ts'; import { ListEntryBatchOperationUpdateFields } from '../models/ListEntryBatchOperationUpdateFields.ts'; import { ListEntryWithEntity } from '../models/ListEntryWithEntity.ts'; @@ -22,6 +21,7 @@ import { ListEntryWithEntityPaged } from '../models/ListEntryWithEntityPaged.ts' import { ListWithType } from '../models/ListWithType.ts'; import { ListWithTypePaged } from '../models/ListWithTypePaged.ts'; import { NotFoundErrors } from '../models/NotFoundErrors.ts'; +import { Responses400 } from '../models/Responses400.ts'; import { SavedView } from '../models/SavedView.ts'; import { SavedViewPaged } from '../models/SavedViewPaged.ts'; @@ -31,165 +31,7 @@ import { SavedViewPaged } from '../models/SavedViewPaged.ts'; export class ListsApiRequestFactory extends BaseAPIRequestFactory { /** - * Returns metadata on the Saved Views on a List. - * Get metadata on Saved Views - * @param listId List ID - * @param cursor Cursor for the next or previous page - * @param limit Number of items to include in the page - */ - public async getV2ListsListidSavedViews(listId: number, cursor?: string, limit?: number, _options?: Configuration): Promise { - let _config = _options || this.configuration; - - // verify required parameter 'listId' is not null or undefined - if (listId === null || listId === undefined) { - throw new RequiredError("ListsApi", "getV2ListsListidSavedViews", "listId"); - } - - - - - // Path Params - const localVarPath = '/v2/lists/{listId}/saved-views' - .replace('{' + 'listId' + '}', encodeURIComponent(String(listId))); - - // Make Request Context - const requestContext = _config.baseServer.makeRequestContext(localVarPath, HttpMethod.GET); - requestContext.setHeaderParam("Accept", "application/json, */*;q=0.8") - - // Query Params - if (cursor !== undefined) { - requestContext.setQueryParam("cursor", ObjectSerializer.serialize(cursor, "string", "")); - } - - // Query Params - if (limit !== undefined) { - requestContext.setQueryParam("limit", ObjectSerializer.serialize(limit, "number", "int32")); - } - - - let authMethod: SecurityAuthentication | undefined; - // Apply auth methods - authMethod = _config.authMethods["bearerAuth"] - if (authMethod?.applySecurityAuthentication) { - await authMethod?.applySecurityAuthentication(requestContext); - } - - const defaultAuth: SecurityAuthentication | undefined = _config?.authMethods?.default - if (defaultAuth?.applySecurityAuthentication) { - await defaultAuth?.applySecurityAuthentication(requestContext); - } - - return requestContext; - } - - /** - * Returns metadata on a single Saved View. - * Get metadata on a single Saved View - * @param listId List ID - * @param viewId Saved view ID - */ - public async getV2ListsListidSavedViewsViewid(listId: number, viewId: number, _options?: Configuration): Promise { - let _config = _options || this.configuration; - - // verify required parameter 'listId' is not null or undefined - if (listId === null || listId === undefined) { - throw new RequiredError("ListsApi", "getV2ListsListidSavedViewsViewid", "listId"); - } - - - // verify required parameter 'viewId' is not null or undefined - if (viewId === null || viewId === undefined) { - throw new RequiredError("ListsApi", "getV2ListsListidSavedViewsViewid", "viewId"); - } - - - // Path Params - const localVarPath = '/v2/lists/{listId}/saved-views/{viewId}' - .replace('{' + 'listId' + '}', encodeURIComponent(String(listId))) - .replace('{' + 'viewId' + '}', encodeURIComponent(String(viewId))); - - // Make Request Context - const requestContext = _config.baseServer.makeRequestContext(localVarPath, HttpMethod.GET); - requestContext.setHeaderParam("Accept", "application/json, */*;q=0.8") - - - let authMethod: SecurityAuthentication | undefined; - // Apply auth methods - authMethod = _config.authMethods["bearerAuth"] - if (authMethod?.applySecurityAuthentication) { - await authMethod?.applySecurityAuthentication(requestContext); - } - - const defaultAuth: SecurityAuthentication | undefined = _config?.authMethods?.default - if (defaultAuth?.applySecurityAuthentication) { - await defaultAuth?.applySecurityAuthentication(requestContext); - } - - return requestContext; - } - - /** - * Paginate through the List Entries (AKA rows) on a given Saved View. Use this endpoint when you need to filter entities or only want **some** field data to be returned: This endpoint respects the filters set on a Saved View via web app, and only returns field data corresponding to the columns that have been pulled into the Saved View via web app. Though this endpoint respects the Saved View\'s filters and column/Field selection, it does not yet preserve sort order. This endpoint also only supports **sheet-type Saved Views**, and not board- or dashboard-type Saved Views. See the [Data Model](#section/Data-Model) section for more information about Saved Views. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Get all List Entries on a Saved View - * @param listId List ID - * @param viewId Saved view ID - * @param cursor Cursor for the next or previous page - * @param limit Number of items to include in the page - */ - public async getV2ListsListidSavedViewsViewidListEntries(listId: number, viewId: number, cursor?: string, limit?: number, _options?: Configuration): Promise { - let _config = _options || this.configuration; - - // verify required parameter 'listId' is not null or undefined - if (listId === null || listId === undefined) { - throw new RequiredError("ListsApi", "getV2ListsListidSavedViewsViewidListEntries", "listId"); - } - - - // verify required parameter 'viewId' is not null or undefined - if (viewId === null || viewId === undefined) { - throw new RequiredError("ListsApi", "getV2ListsListidSavedViewsViewidListEntries", "viewId"); - } - - - - - // Path Params - const localVarPath = '/v2/lists/{listId}/saved-views/{viewId}/list-entries' - .replace('{' + 'listId' + '}', encodeURIComponent(String(listId))) - .replace('{' + 'viewId' + '}', encodeURIComponent(String(viewId))); - - // Make Request Context - const requestContext = _config.baseServer.makeRequestContext(localVarPath, HttpMethod.GET); - requestContext.setHeaderParam("Accept", "application/json, */*;q=0.8") - - // Query Params - if (cursor !== undefined) { - requestContext.setQueryParam("cursor", ObjectSerializer.serialize(cursor, "string", "")); - } - - // Query Params - if (limit !== undefined) { - requestContext.setQueryParam("limit", ObjectSerializer.serialize(limit, "number", "int32")); - } - - - let authMethod: SecurityAuthentication | undefined; - // Apply auth methods - authMethod = _config.authMethods["bearerAuth"] - if (authMethod?.applySecurityAuthentication) { - await authMethod?.applySecurityAuthentication(requestContext); - } - - const defaultAuth: SecurityAuthentication | undefined = _config?.authMethods?.default - if (defaultAuth?.applySecurityAuthentication) { - await defaultAuth?.applySecurityAuthentication(requestContext); - } - - return requestContext; - } - - /** - * Returns metadata on Lists. + * Paginate through all Lists in your organization that you have access to view. Returns basic information about each List, including name, owner, and privacy settings. * Get metadata on all Lists * @param cursor Cursor for the next or previous page * @param limit Number of items to include in the page @@ -285,7 +127,7 @@ export class ListsApiRequestFactory extends BaseAPIRequestFactory { } /** - * Returns metadata on a single List. + * Retrieve detailed information about a specific List you have access to view. Returns List configuration including name, owner, privacy settings, and creation details. * Get metadata on a single List * @param listId List ID */ @@ -364,7 +206,7 @@ export class ListsApiRequestFactory extends BaseAPIRequestFactory { // Query Params if (fieldIds !== undefined) { - const serializedParams = ObjectSerializer.serialize(fieldIds, "Array", "string"); + const serializedParams = ObjectSerializer.serialize(fieldIds, "Array", ""); for (const serializedParam of serializedParams) { requestContext.appendQueryParam("fieldIds", serializedParam); } @@ -372,7 +214,7 @@ export class ListsApiRequestFactory extends BaseAPIRequestFactory { // Query Params if (fieldTypes !== undefined) { - const serializedParams = ObjectSerializer.serialize(fieldTypes, "Array<'enriched' | 'global' | 'list' | 'relationship-intelligence'>", "string"); + const serializedParams = ObjectSerializer.serialize(fieldTypes, "Array<'enriched' | 'global' | 'list' | 'relationship-intelligence'>", ""); for (const serializedParam of serializedParams) { requestContext.appendQueryParam("fieldTypes", serializedParam); } @@ -395,8 +237,8 @@ export class ListsApiRequestFactory extends BaseAPIRequestFactory { } /** - * | ⚠️ This endpoint is currently in BETA | |--| Returns a single field value on a list entry. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Get a single field value [BETA] + * Returns a single field value on a list entry. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Get a single field value * @param listId List ID * @param listEntryId List Entry ID * @param fieldId Field ID @@ -449,8 +291,8 @@ export class ListsApiRequestFactory extends BaseAPIRequestFactory { } /** - * | ⚠️ This endpoint is currently in BETA | |--| Update a single field value. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Update a single field value on a List Entry [BETA] + * Update a single field value. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Update a single field value on a List Entry * @param listId List ID * @param listEntryId List Entry ID * @param fieldId Field ID @@ -521,8 +363,8 @@ export class ListsApiRequestFactory extends BaseAPIRequestFactory { } /** - * | ⚠️ This endpoint is currently in BETA | |--| Paginate through all field values on a single list entry. All fields will be included by default. The `ids` and `types` parameters can be used to filter the collection. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Get field values on a single List Entry [BETA] + * Paginate through all field values on a single list entry. All fields will be included by default. The `ids` and `types` parameters can be used to filter the collection. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Get field values on a single List Entry * @param listId List ID * @param listEntryId List Entry ID * @param ids Field IDs for which to return field data @@ -560,7 +402,7 @@ export class ListsApiRequestFactory extends BaseAPIRequestFactory { // Query Params if (ids !== undefined) { - const serializedParams = ObjectSerializer.serialize(ids, "Array", "string"); + const serializedParams = ObjectSerializer.serialize(ids, "Array", ""); for (const serializedParam of serializedParams) { requestContext.appendQueryParam("ids", serializedParam); } @@ -568,7 +410,7 @@ export class ListsApiRequestFactory extends BaseAPIRequestFactory { // Query Params if (types !== undefined) { - const serializedParams = ObjectSerializer.serialize(types, "Array<'enriched' | 'global' | 'list' | 'relationship-intelligence'>", "string"); + const serializedParams = ObjectSerializer.serialize(types, "Array<'enriched' | 'global' | 'list' | 'relationship-intelligence'>", ""); for (const serializedParam of serializedParams) { requestContext.appendQueryParam("types", serializedParam); } @@ -601,8 +443,8 @@ export class ListsApiRequestFactory extends BaseAPIRequestFactory { } /** - * | ⚠️ This endpoint is currently in BETA | |--| Perform batch operations on a list entry\'s fields. Currently the only operation at the endpoint is `update-fields`, which allows you to update multiple field values with a single request. This is equivalent to calling [the single field update](#operation/v2_lists_listId_list-entries_listEntryId_fields_fieldId__POST) endpoint multiple times. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Perform batch operations on a list entry\'s fields [BETA] + * Perform batch operations on a list entry\'s fields. Currently the only operation at the endpoint is `update-fields`, which allows you to update multiple field values with a single request. This is equivalent to calling [the single field update](#operation/v2_lists_listId_list-entries_listEntryId_fields_fieldId__POST) endpoint multiple times. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Perform batch operations on a list entry\'s fields * @param listId List ID * @param listEntryId List Entry ID * @param body @@ -665,8 +507,8 @@ export class ListsApiRequestFactory extends BaseAPIRequestFactory { } /** - * | ⚠️ This endpoint is currently in BETA | |--| Retrieve a single list entry. Returns basic information and field data, including list-specific field data. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/lists/{listId}/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, the List Entry will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Get a single List Entry on a List [BETA] + * Retrieve a single list entry. Returns basic information and field data, including list-specific field data. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/lists/{listId}/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, the List Entry will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Get a single List Entry on a List * @param listId List ID * @param listEntryId List Entry ID * @param fieldIds Field IDs for which to return field data @@ -700,7 +542,7 @@ export class ListsApiRequestFactory extends BaseAPIRequestFactory { // Query Params if (fieldIds !== undefined) { - const serializedParams = ObjectSerializer.serialize(fieldIds, "Array", "string"); + const serializedParams = ObjectSerializer.serialize(fieldIds, "Array", ""); for (const serializedParam of serializedParams) { requestContext.appendQueryParam("fieldIds", serializedParam); } @@ -708,7 +550,7 @@ export class ListsApiRequestFactory extends BaseAPIRequestFactory { // Query Params if (fieldTypes !== undefined) { - const serializedParams = ObjectSerializer.serialize(fieldTypes, "Array<'enriched' | 'global' | 'list' | 'relationship-intelligence'>", "string"); + const serializedParams = ObjectSerializer.serialize(fieldTypes, "Array<'enriched' | 'global' | 'list' | 'relationship-intelligence'>", ""); for (const serializedParam of serializedParams) { requestContext.appendQueryParam("fieldTypes", serializedParam); } @@ -730,167 +572,168 @@ export class ListsApiRequestFactory extends BaseAPIRequestFactory { return requestContext; } -} - -export class ListsApiResponseProcessor { - /** - * Unwraps the actual response sent by the server from the response context and deserializes the response content - * to the expected objects - * - * @params response Response returned by the server for a request to getV2ListsListidSavedViews - * @throws ApiException if the response code was not in [200, 299] + * Paginate through all Saved Views you have access to view for a specific List. Returns Saved View configurations including name, column settings, and owner information. + * Get metadata on Saved Views + * @param listId List ID + * @param cursor Cursor for the next or previous page + * @param limit Number of items to include in the page */ - public async getV2ListsListidSavedViewsWithHttpInfo(response: ResponseContext): Promise> { - const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); - if (isCodeInRange("200", response.httpStatusCode)) { - const body: SavedViewPaged = ObjectSerializer.deserialize( - ObjectSerializer.parse(await response.body.text(), contentType), - "SavedViewPaged", "" - ) as SavedViewPaged; - return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); - } - if (isCodeInRange("400", response.httpStatusCode)) { - const body: InlineObject = ObjectSerializer.deserialize( - ObjectSerializer.parse(await response.body.text(), contentType), - "InlineObject", "" - ) as InlineObject; - throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + public async v2ListsListIdSavedViewsGET(listId: number, cursor?: string, limit?: number, _options?: Configuration): Promise { + let _config = _options || this.configuration; + + // verify required parameter 'listId' is not null or undefined + if (listId === null || listId === undefined) { + throw new RequiredError("ListsApi", "v2ListsListIdSavedViewsGET", "listId"); } - if (isCodeInRange("404", response.httpStatusCode)) { - const body: NotFoundErrors = ObjectSerializer.deserialize( - ObjectSerializer.parse(await response.body.text(), contentType), - "NotFoundErrors", "" - ) as NotFoundErrors; - throw new ApiException(response.httpStatusCode, "Not Found", body, response.headers); + + + + + // Path Params + const localVarPath = '/v2/lists/{listId}/saved-views' + .replace('{' + 'listId' + '}', encodeURIComponent(String(listId))); + + // Make Request Context + const requestContext = _config.baseServer.makeRequestContext(localVarPath, HttpMethod.GET); + requestContext.setHeaderParam("Accept", "application/json, */*;q=0.8") + + // Query Params + if (cursor !== undefined) { + requestContext.setQueryParam("cursor", ObjectSerializer.serialize(cursor, "string", "")); } - if (isCodeInRange("0", response.httpStatusCode)) { - const body: Errors = ObjectSerializer.deserialize( - ObjectSerializer.parse(await response.body.text(), contentType), - "Errors", "" - ) as Errors; - throw new ApiException(response.httpStatusCode, "Errors", body, response.headers); + + // Query Params + if (limit !== undefined) { + requestContext.setQueryParam("limit", ObjectSerializer.serialize(limit, "number", "int32")); } - // Work around for missing responses in specification, e.g. for petstore.yaml - if (response.httpStatusCode >= 200 && response.httpStatusCode <= 299) { - const body: SavedViewPaged = ObjectSerializer.deserialize( - ObjectSerializer.parse(await response.body.text(), contentType), - "SavedViewPaged", "" - ) as SavedViewPaged; - return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + + let authMethod: SecurityAuthentication | undefined; + // Apply auth methods + authMethod = _config.authMethods["bearerAuth"] + if (authMethod?.applySecurityAuthentication) { + await authMethod?.applySecurityAuthentication(requestContext); + } + + const defaultAuth: SecurityAuthentication | undefined = _config?.authMethods?.default + if (defaultAuth?.applySecurityAuthentication) { + await defaultAuth?.applySecurityAuthentication(requestContext); } - throw new ApiException(response.httpStatusCode, "Unknown API Status Code!", await response.getBodyAsAny(), response.headers); + return requestContext; } /** - * Unwraps the actual response sent by the server from the response context and deserializes the response content - * to the expected objects - * - * @params response Response returned by the server for a request to getV2ListsListidSavedViewsViewid - * @throws ApiException if the response code was not in [200, 299] + * Retrieve detailed information about a specific Saved View you have access to view. Returns complete Saved View configuration including name, sorting, and column visibility settings. + * Get metadata on a single Saved View + * @param listId List ID + * @param viewId Saved view ID */ - public async getV2ListsListidSavedViewsViewidWithHttpInfo(response: ResponseContext): Promise> { - const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); - if (isCodeInRange("200", response.httpStatusCode)) { - const body: SavedView = ObjectSerializer.deserialize( - ObjectSerializer.parse(await response.body.text(), contentType), - "SavedView", "" - ) as SavedView; - return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); - } - if (isCodeInRange("400", response.httpStatusCode)) { - const body: InlineObject = ObjectSerializer.deserialize( - ObjectSerializer.parse(await response.body.text(), contentType), - "InlineObject", "" - ) as InlineObject; - throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + public async v2ListsListIdSavedViewsViewIdGET(listId: number, viewId: number, _options?: Configuration): Promise { + let _config = _options || this.configuration; + + // verify required parameter 'listId' is not null or undefined + if (listId === null || listId === undefined) { + throw new RequiredError("ListsApi", "v2ListsListIdSavedViewsViewIdGET", "listId"); } - if (isCodeInRange("404", response.httpStatusCode)) { - const body: NotFoundErrors = ObjectSerializer.deserialize( - ObjectSerializer.parse(await response.body.text(), contentType), - "NotFoundErrors", "" - ) as NotFoundErrors; - throw new ApiException(response.httpStatusCode, "Not Found", body, response.headers); - } - if (isCodeInRange("0", response.httpStatusCode)) { - const body: Errors = ObjectSerializer.deserialize( - ObjectSerializer.parse(await response.body.text(), contentType), - "Errors", "" - ) as Errors; - throw new ApiException(response.httpStatusCode, "Errors", body, response.headers); + + + // verify required parameter 'viewId' is not null or undefined + if (viewId === null || viewId === undefined) { + throw new RequiredError("ListsApi", "v2ListsListIdSavedViewsViewIdGET", "viewId"); } - // Work around for missing responses in specification, e.g. for petstore.yaml - if (response.httpStatusCode >= 200 && response.httpStatusCode <= 299) { - const body: SavedView = ObjectSerializer.deserialize( - ObjectSerializer.parse(await response.body.text(), contentType), - "SavedView", "" - ) as SavedView; - return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + + // Path Params + const localVarPath = '/v2/lists/{listId}/saved-views/{viewId}' + .replace('{' + 'listId' + '}', encodeURIComponent(String(listId))) + .replace('{' + 'viewId' + '}', encodeURIComponent(String(viewId))); + + // Make Request Context + const requestContext = _config.baseServer.makeRequestContext(localVarPath, HttpMethod.GET); + requestContext.setHeaderParam("Accept", "application/json, */*;q=0.8") + + + let authMethod: SecurityAuthentication | undefined; + // Apply auth methods + authMethod = _config.authMethods["bearerAuth"] + if (authMethod?.applySecurityAuthentication) { + await authMethod?.applySecurityAuthentication(requestContext); + } + + const defaultAuth: SecurityAuthentication | undefined = _config?.authMethods?.default + if (defaultAuth?.applySecurityAuthentication) { + await defaultAuth?.applySecurityAuthentication(requestContext); } - throw new ApiException(response.httpStatusCode, "Unknown API Status Code!", await response.getBodyAsAny(), response.headers); + return requestContext; } /** - * Unwraps the actual response sent by the server from the response context and deserializes the response content - * to the expected objects - * - * @params response Response returned by the server for a request to getV2ListsListidSavedViewsViewidListEntries - * @throws ApiException if the response code was not in [200, 299] + * Paginate through the List Entries (AKA rows) on a given Saved View. Use this endpoint when you need to filter entities or only want **some** field data to be returned: This endpoint respects the filters set on a Saved View via web app, and only returns field data corresponding to the columns that have been pulled into the Saved View via web app. Though this endpoint respects the Saved View\'s filters and column/Field selection, it does not yet preserve sort order. This endpoint also only supports **sheet-type Saved Views**, and not board- or dashboard-type Saved Views. See the [Data Model](#section/Data-Model) section for more information about Saved Views. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Get all List Entries on a Saved View + * @param listId List ID + * @param viewId Saved view ID + * @param cursor Cursor for the next or previous page + * @param limit Number of items to include in the page */ - public async getV2ListsListidSavedViewsViewidListEntriesWithHttpInfo(response: ResponseContext): Promise> { - const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); - if (isCodeInRange("200", response.httpStatusCode)) { - const body: ListEntryWithEntityPaged = ObjectSerializer.deserialize( - ObjectSerializer.parse(await response.body.text(), contentType), - "ListEntryWithEntityPaged", "" - ) as ListEntryWithEntityPaged; - return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); - } - if (isCodeInRange("400", response.httpStatusCode)) { - const body: InlineObject = ObjectSerializer.deserialize( - ObjectSerializer.parse(await response.body.text(), contentType), - "InlineObject", "" - ) as InlineObject; - throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + public async v2ListsListIdSavedViewsViewIdListEntriesGET(listId: number, viewId: number, cursor?: string, limit?: number, _options?: Configuration): Promise { + let _config = _options || this.configuration; + + // verify required parameter 'listId' is not null or undefined + if (listId === null || listId === undefined) { + throw new RequiredError("ListsApi", "v2ListsListIdSavedViewsViewIdListEntriesGET", "listId"); } - if (isCodeInRange("403", response.httpStatusCode)) { - const body: AuthorizationErrors = ObjectSerializer.deserialize( - ObjectSerializer.parse(await response.body.text(), contentType), - "AuthorizationErrors", "" - ) as AuthorizationErrors; - throw new ApiException(response.httpStatusCode, "Forbidden", body, response.headers); + + + // verify required parameter 'viewId' is not null or undefined + if (viewId === null || viewId === undefined) { + throw new RequiredError("ListsApi", "v2ListsListIdSavedViewsViewIdListEntriesGET", "viewId"); } - if (isCodeInRange("404", response.httpStatusCode)) { - const body: NotFoundErrors = ObjectSerializer.deserialize( - ObjectSerializer.parse(await response.body.text(), contentType), - "NotFoundErrors", "" - ) as NotFoundErrors; - throw new ApiException(response.httpStatusCode, "Not Found", body, response.headers); + + + + + // Path Params + const localVarPath = '/v2/lists/{listId}/saved-views/{viewId}/list-entries' + .replace('{' + 'listId' + '}', encodeURIComponent(String(listId))) + .replace('{' + 'viewId' + '}', encodeURIComponent(String(viewId))); + + // Make Request Context + const requestContext = _config.baseServer.makeRequestContext(localVarPath, HttpMethod.GET); + requestContext.setHeaderParam("Accept", "application/json, */*;q=0.8") + + // Query Params + if (cursor !== undefined) { + requestContext.setQueryParam("cursor", ObjectSerializer.serialize(cursor, "string", "")); } - if (isCodeInRange("0", response.httpStatusCode)) { - const body: Errors = ObjectSerializer.deserialize( - ObjectSerializer.parse(await response.body.text(), contentType), - "Errors", "" - ) as Errors; - throw new ApiException(response.httpStatusCode, "Errors", body, response.headers); + + // Query Params + if (limit !== undefined) { + requestContext.setQueryParam("limit", ObjectSerializer.serialize(limit, "number", "int32")); } - // Work around for missing responses in specification, e.g. for petstore.yaml - if (response.httpStatusCode >= 200 && response.httpStatusCode <= 299) { - const body: ListEntryWithEntityPaged = ObjectSerializer.deserialize( - ObjectSerializer.parse(await response.body.text(), contentType), - "ListEntryWithEntityPaged", "" - ) as ListEntryWithEntityPaged; - return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + + let authMethod: SecurityAuthentication | undefined; + // Apply auth methods + authMethod = _config.authMethods["bearerAuth"] + if (authMethod?.applySecurityAuthentication) { + await authMethod?.applySecurityAuthentication(requestContext); + } + + const defaultAuth: SecurityAuthentication | undefined = _config?.authMethods?.default + if (defaultAuth?.applySecurityAuthentication) { + await defaultAuth?.applySecurityAuthentication(requestContext); } - throw new ApiException(response.httpStatusCode, "Unknown API Status Code!", await response.getBodyAsAny(), response.headers); + return requestContext; } +} + +export class ListsApiResponseProcessor { + /** * Unwraps the actual response sent by the server from the response context and deserializes the response content * to the expected objects @@ -908,11 +751,11 @@ export class ListsApiResponseProcessor { return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); } if (isCodeInRange("400", response.httpStatusCode)) { - const body: InlineObject = ObjectSerializer.deserialize( + const body: Responses400 = ObjectSerializer.deserialize( ObjectSerializer.parse(await response.body.text(), contentType), - "InlineObject", "" - ) as InlineObject; - throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); } if (isCodeInRange("0", response.httpStatusCode)) { const body: Errors = ObjectSerializer.deserialize( @@ -951,11 +794,11 @@ export class ListsApiResponseProcessor { return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); } if (isCodeInRange("400", response.httpStatusCode)) { - const body: InlineObject = ObjectSerializer.deserialize( + const body: Responses400 = ObjectSerializer.deserialize( ObjectSerializer.parse(await response.body.text(), contentType), - "InlineObject", "" - ) as InlineObject; - throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); } if (isCodeInRange("404", response.httpStatusCode)) { const body: NotFoundErrors = ObjectSerializer.deserialize( @@ -1001,11 +844,11 @@ export class ListsApiResponseProcessor { return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); } if (isCodeInRange("400", response.httpStatusCode)) { - const body: InlineObject = ObjectSerializer.deserialize( + const body: Responses400 = ObjectSerializer.deserialize( ObjectSerializer.parse(await response.body.text(), contentType), - "InlineObject", "" - ) as InlineObject; - throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); } if (isCodeInRange("404", response.httpStatusCode)) { const body: NotFoundErrors = ObjectSerializer.deserialize( @@ -1051,11 +894,11 @@ export class ListsApiResponseProcessor { return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); } if (isCodeInRange("400", response.httpStatusCode)) { - const body: InlineObject = ObjectSerializer.deserialize( + const body: Responses400 = ObjectSerializer.deserialize( ObjectSerializer.parse(await response.body.text(), contentType), - "InlineObject", "" - ) as InlineObject; - throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); } if (isCodeInRange("403", response.httpStatusCode)) { const body: AuthorizationErrors = ObjectSerializer.deserialize( @@ -1108,11 +951,11 @@ export class ListsApiResponseProcessor { return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); } if (isCodeInRange("400", response.httpStatusCode)) { - const body: InlineObject = ObjectSerializer.deserialize( + const body: Responses400 = ObjectSerializer.deserialize( ObjectSerializer.parse(await response.body.text(), contentType), - "InlineObject", "" - ) as InlineObject; - throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); } if (isCodeInRange("403", response.httpStatusCode)) { const body: AuthorizationErrors = ObjectSerializer.deserialize( @@ -1161,11 +1004,11 @@ export class ListsApiResponseProcessor { return new HttpInfo(response.httpStatusCode, response.headers, response.body, undefined); } if (isCodeInRange("400", response.httpStatusCode)) { - const body: InlineObject = ObjectSerializer.deserialize( + const body: Responses400 = ObjectSerializer.deserialize( ObjectSerializer.parse(await response.body.text(), contentType), - "InlineObject", "" - ) as InlineObject; - throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); } if (isCodeInRange("403", response.httpStatusCode)) { const body: AuthorizationErrors = ObjectSerializer.deserialize( @@ -1218,11 +1061,11 @@ export class ListsApiResponseProcessor { return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); } if (isCodeInRange("400", response.httpStatusCode)) { - const body: InlineObject = ObjectSerializer.deserialize( + const body: Responses400 = ObjectSerializer.deserialize( ObjectSerializer.parse(await response.body.text(), contentType), - "InlineObject", "" - ) as InlineObject; - throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); } if (isCodeInRange("403", response.httpStatusCode)) { const body: AuthorizationErrors = ObjectSerializer.deserialize( @@ -1275,11 +1118,11 @@ export class ListsApiResponseProcessor { return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); } if (isCodeInRange("400", response.httpStatusCode)) { - const body: InlineObject = ObjectSerializer.deserialize( + const body: Responses400 = ObjectSerializer.deserialize( ObjectSerializer.parse(await response.body.text(), contentType), - "InlineObject", "" - ) as InlineObject; - throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); } if (isCodeInRange("403", response.httpStatusCode)) { const body: AuthorizationErrors = ObjectSerializer.deserialize( @@ -1332,11 +1175,11 @@ export class ListsApiResponseProcessor { return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); } if (isCodeInRange("400", response.httpStatusCode)) { - const body: InlineObject = ObjectSerializer.deserialize( + const body: Responses400 = ObjectSerializer.deserialize( ObjectSerializer.parse(await response.body.text(), contentType), - "InlineObject", "" - ) as InlineObject; - throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); } if (isCodeInRange("403", response.httpStatusCode)) { const body: AuthorizationErrors = ObjectSerializer.deserialize( @@ -1372,4 +1215,161 @@ export class ListsApiResponseProcessor { throw new ApiException(response.httpStatusCode, "Unknown API Status Code!", await response.getBodyAsAny(), response.headers); } + /** + * Unwraps the actual response sent by the server from the response context and deserializes the response content + * to the expected objects + * + * @params response Response returned by the server for a request to v2ListsListIdSavedViewsGET + * @throws ApiException if the response code was not in [200, 299] + */ + public async v2ListsListIdSavedViewsGETWithHttpInfo(response: ResponseContext): Promise> { + const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); + if (isCodeInRange("200", response.httpStatusCode)) { + const body: SavedViewPaged = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "SavedViewPaged", "" + ) as SavedViewPaged; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + if (isCodeInRange("400", response.httpStatusCode)) { + const body: Responses400 = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + } + if (isCodeInRange("404", response.httpStatusCode)) { + const body: NotFoundErrors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "NotFoundErrors", "" + ) as NotFoundErrors; + throw new ApiException(response.httpStatusCode, "Not Found", body, response.headers); + } + if (isCodeInRange("0", response.httpStatusCode)) { + const body: Errors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Errors", "" + ) as Errors; + throw new ApiException(response.httpStatusCode, "Errors", body, response.headers); + } + + // Work around for missing responses in specification, e.g. for petstore.yaml + if (response.httpStatusCode >= 200 && response.httpStatusCode <= 299) { + const body: SavedViewPaged = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "SavedViewPaged", "" + ) as SavedViewPaged; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + + throw new ApiException(response.httpStatusCode, "Unknown API Status Code!", await response.getBodyAsAny(), response.headers); + } + + /** + * Unwraps the actual response sent by the server from the response context and deserializes the response content + * to the expected objects + * + * @params response Response returned by the server for a request to v2ListsListIdSavedViewsViewIdGET + * @throws ApiException if the response code was not in [200, 299] + */ + public async v2ListsListIdSavedViewsViewIdGETWithHttpInfo(response: ResponseContext): Promise> { + const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); + if (isCodeInRange("200", response.httpStatusCode)) { + const body: SavedView = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "SavedView", "" + ) as SavedView; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + if (isCodeInRange("400", response.httpStatusCode)) { + const body: Responses400 = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + } + if (isCodeInRange("404", response.httpStatusCode)) { + const body: NotFoundErrors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "NotFoundErrors", "" + ) as NotFoundErrors; + throw new ApiException(response.httpStatusCode, "Not Found", body, response.headers); + } + if (isCodeInRange("0", response.httpStatusCode)) { + const body: Errors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Errors", "" + ) as Errors; + throw new ApiException(response.httpStatusCode, "Errors", body, response.headers); + } + + // Work around for missing responses in specification, e.g. for petstore.yaml + if (response.httpStatusCode >= 200 && response.httpStatusCode <= 299) { + const body: SavedView = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "SavedView", "" + ) as SavedView; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + + throw new ApiException(response.httpStatusCode, "Unknown API Status Code!", await response.getBodyAsAny(), response.headers); + } + + /** + * Unwraps the actual response sent by the server from the response context and deserializes the response content + * to the expected objects + * + * @params response Response returned by the server for a request to v2ListsListIdSavedViewsViewIdListEntriesGET + * @throws ApiException if the response code was not in [200, 299] + */ + public async v2ListsListIdSavedViewsViewIdListEntriesGETWithHttpInfo(response: ResponseContext): Promise> { + const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); + if (isCodeInRange("200", response.httpStatusCode)) { + const body: ListEntryWithEntityPaged = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "ListEntryWithEntityPaged", "" + ) as ListEntryWithEntityPaged; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + if (isCodeInRange("400", response.httpStatusCode)) { + const body: Responses400 = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + } + if (isCodeInRange("403", response.httpStatusCode)) { + const body: AuthorizationErrors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "AuthorizationErrors", "" + ) as AuthorizationErrors; + throw new ApiException(response.httpStatusCode, "Forbidden", body, response.headers); + } + if (isCodeInRange("404", response.httpStatusCode)) { + const body: NotFoundErrors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "NotFoundErrors", "" + ) as NotFoundErrors; + throw new ApiException(response.httpStatusCode, "Not Found", body, response.headers); + } + if (isCodeInRange("0", response.httpStatusCode)) { + const body: Errors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Errors", "" + ) as Errors; + throw new ApiException(response.httpStatusCode, "Errors", body, response.headers); + } + + // Work around for missing responses in specification, e.g. for petstore.yaml + if (response.httpStatusCode >= 200 && response.httpStatusCode <= 299) { + const body: ListEntryWithEntityPaged = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "ListEntryWithEntityPaged", "" + ) as ListEntryWithEntityPaged; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + + throw new ApiException(response.httpStatusCode, "Unknown API Status Code!", await response.getBodyAsAny(), response.headers); + } + } diff --git a/src/v2/generated/apis/MeetingsApi.ts b/src/v2/generated/apis/MeetingsApi.ts new file mode 100644 index 0000000..713c137 --- /dev/null +++ b/src/v2/generated/apis/MeetingsApi.ts @@ -0,0 +1,118 @@ +// TODO: better import syntax? +import {BaseAPIRequestFactory, RequiredError, COLLECTION_FORMATS} from './baseapi.ts'; +import {Configuration} from '../configuration.ts'; +import {RequestContext, HttpMethod, ResponseContext, HttpFile, HttpInfo} from '../http/http.ts'; +import {ObjectSerializer} from '../models/ObjectSerializer.ts'; +import {ApiException} from './exception.ts'; +import {canConsumeForm, isCodeInRange} from '../util.ts'; +import {SecurityAuthentication} from '../auth/auth.ts'; + + +import { Errors } from '../models/Errors.ts'; +import { InteractionsMeetingPaged } from '../models/InteractionsMeetingPaged.ts'; +import { Responses400 } from '../models/Responses400.ts'; + +/** + * no description + */ +export class MeetingsApiRequestFactory extends BaseAPIRequestFactory { + + /** + * Paginate through all Meetings in Affinity. Returns basic information about past and future meeting interactions and its attendees. You can filter meetings using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|----------------------------------| | `id` | Unique identifier for Meetings | `int64` | `=` | `id=1` | | `startTime` | Start time of when Meeting was scheduled | `datetime` | `>`, `<`, `>=`, `<=` | `startTime>2025-01-01T01:00:00Z` | | `createdAt` | When the Meeting was created in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-01-01T01:00:00Z` | | `updatedAt` | When the Meeting was updated in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-01-01T01:00:00Z`| + * Get metadata on all Meetings + * @param cursor Cursor for the next or previous page + * @param limit Number of items to include in the page + * @param filter Filter options + */ + public async v2MeetingsGET(cursor?: string, limit?: number, filter?: string, _options?: Configuration): Promise { + let _config = _options || this.configuration; + + + + + // Path Params + const localVarPath = '/v2/meetings'; + + // Make Request Context + const requestContext = _config.baseServer.makeRequestContext(localVarPath, HttpMethod.GET); + requestContext.setHeaderParam("Accept", "application/json, */*;q=0.8") + + // Query Params + if (cursor !== undefined) { + requestContext.setQueryParam("cursor", ObjectSerializer.serialize(cursor, "string", "")); + } + + // Query Params + if (limit !== undefined) { + requestContext.setQueryParam("limit", ObjectSerializer.serialize(limit, "number", "int32")); + } + + // Query Params + if (filter !== undefined) { + requestContext.setQueryParam("filter", ObjectSerializer.serialize(filter, "string", "")); + } + + + let authMethod: SecurityAuthentication | undefined; + // Apply auth methods + authMethod = _config.authMethods["bearerAuth"] + if (authMethod?.applySecurityAuthentication) { + await authMethod?.applySecurityAuthentication(requestContext); + } + + const defaultAuth: SecurityAuthentication | undefined = _config?.authMethods?.default + if (defaultAuth?.applySecurityAuthentication) { + await defaultAuth?.applySecurityAuthentication(requestContext); + } + + return requestContext; + } + +} + +export class MeetingsApiResponseProcessor { + + /** + * Unwraps the actual response sent by the server from the response context and deserializes the response content + * to the expected objects + * + * @params response Response returned by the server for a request to v2MeetingsGET + * @throws ApiException if the response code was not in [200, 299] + */ + public async v2MeetingsGETWithHttpInfo(response: ResponseContext): Promise> { + const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); + if (isCodeInRange("200", response.httpStatusCode)) { + const body: InteractionsMeetingPaged = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "InteractionsMeetingPaged", "" + ) as InteractionsMeetingPaged; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + if (isCodeInRange("400", response.httpStatusCode)) { + const body: Responses400 = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + } + if (isCodeInRange("0", response.httpStatusCode)) { + const body: Errors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Errors", "" + ) as Errors; + throw new ApiException(response.httpStatusCode, "Errors", body, response.headers); + } + + // Work around for missing responses in specification, e.g. for petstore.yaml + if (response.httpStatusCode >= 200 && response.httpStatusCode <= 299) { + const body: InteractionsMeetingPaged = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "InteractionsMeetingPaged", "" + ) as InteractionsMeetingPaged; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + + throw new ApiException(response.httpStatusCode, "Unknown API Status Code!", await response.getBodyAsAny(), response.headers); + } + +} diff --git a/src/v2/generated/apis/NotesApi.ts b/src/v2/generated/apis/NotesApi.ts new file mode 100644 index 0000000..1bd192d --- /dev/null +++ b/src/v2/generated/apis/NotesApi.ts @@ -0,0 +1,689 @@ +// TODO: better import syntax? +import {BaseAPIRequestFactory, RequiredError, COLLECTION_FORMATS} from './baseapi.ts'; +import {Configuration} from '../configuration.ts'; +import {RequestContext, HttpMethod, ResponseContext, HttpFile, HttpInfo} from '../http/http.ts'; +import {ObjectSerializer} from '../models/ObjectSerializer.ts'; +import {ApiException} from './exception.ts'; +import {canConsumeForm, isCodeInRange} from '../util.ts'; +import {SecurityAuthentication} from '../auth/auth.ts'; + + +import { CompanyDataPaged } from '../models/CompanyDataPaged.ts'; +import { Errors } from '../models/Errors.ts'; +import { NotFoundErrors } from '../models/NotFoundErrors.ts'; +import { NotesNote } from '../models/NotesNote.ts'; +import { NotesNotesPaged } from '../models/NotesNotesPaged.ts'; +import { NotesRepliesPaged } from '../models/NotesRepliesPaged.ts'; +import { OpportunityPaged } from '../models/OpportunityPaged.ts'; +import { PersonDataPaged } from '../models/PersonDataPaged.ts'; +import { Responses400 } from '../models/Responses400.ts'; + +/** + * no description + */ +export class NotesApiRequestFactory extends BaseAPIRequestFactory { + + /** + * | ⚠️ This endpoint is currently in BETA | |--| Returns all notes, with the exception of replies. You can filter notes using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|---------------------------------| | `id` | Filter notes by id | `int32` | `=` | `id=1` | | `creator.id` | Filter notes by the creator of the note | `int32` | `=` | `creator.id=1` | | `createdAt` | Filter notes by when it was created | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-02-04T10:48:24Z` | | `updatedAt` | Filter notes by when it was updated | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-02-03T10:48:24Z`| + * Get all Notes + * @param totalCount Include total count of the collection in the pagination response + * @param cursor Cursor for the next or previous page + * @param limit Number of items to include in the page + * @param filter Filter options + * @param includes Additional properties to include in the response + */ + public async v2NotesGET(totalCount?: boolean, cursor?: string, limit?: number, filter?: string, includes?: Set<'companiesPreview' | 'personsPreview' | 'opportunitiesPreview' | 'repliesCount'>, _options?: Configuration): Promise { + let _config = _options || this.configuration; + + + + + + + // Path Params + const localVarPath = '/v2/notes'; + + // Make Request Context + const requestContext = _config.baseServer.makeRequestContext(localVarPath, HttpMethod.GET); + requestContext.setHeaderParam("Accept", "application/json, */*;q=0.8") + + // Query Params + if (totalCount !== undefined) { + requestContext.setQueryParam("totalCount", ObjectSerializer.serialize(totalCount, "boolean", "")); + } + + // Query Params + if (cursor !== undefined) { + requestContext.setQueryParam("cursor", ObjectSerializer.serialize(cursor, "string", "")); + } + + // Query Params + if (limit !== undefined) { + requestContext.setQueryParam("limit", ObjectSerializer.serialize(limit, "number", "int32")); + } + + // Query Params + if (filter !== undefined) { + requestContext.setQueryParam("filter", ObjectSerializer.serialize(filter, "string", "")); + } + + // Query Params + if (includes !== undefined) { + const serializedParams = ObjectSerializer.serialize(includes, "Set<'companiesPreview' | 'personsPreview' | 'opportunitiesPreview' | 'repliesCount'>", ""); + for (const serializedParam of serializedParams) { + requestContext.appendQueryParam("includes", serializedParam); + } + } + + + let authMethod: SecurityAuthentication | undefined; + // Apply auth methods + authMethod = _config.authMethods["bearerAuth"] + if (authMethod?.applySecurityAuthentication) { + await authMethod?.applySecurityAuthentication(requestContext); + } + + const defaultAuth: SecurityAuthentication | undefined = _config?.authMethods?.default + if (defaultAuth?.applySecurityAuthentication) { + await defaultAuth?.applySecurityAuthentication(requestContext); + } + + return requestContext; + } + + /** + * | ⚠️ This endpoint is currently in BETA | |--| Returns directly attached companies for a given Note. + * Get Companies attached to a Note + * @param noteId The id of the Note to get attached Companies + * @param totalCount Include total count of the collection in the pagination response + * @param cursor Cursor for the next or previous page + * @param limit Number of items to include in the page + */ + public async v2NotesNoteIdAttachedCompaniesGET(noteId: number, totalCount?: boolean, cursor?: string, limit?: number, _options?: Configuration): Promise { + let _config = _options || this.configuration; + + // verify required parameter 'noteId' is not null or undefined + if (noteId === null || noteId === undefined) { + throw new RequiredError("NotesApi", "v2NotesNoteIdAttachedCompaniesGET", "noteId"); + } + + + + + + // Path Params + const localVarPath = '/v2/notes/{noteId}/attached-companies' + .replace('{' + 'noteId' + '}', encodeURIComponent(String(noteId))); + + // Make Request Context + const requestContext = _config.baseServer.makeRequestContext(localVarPath, HttpMethod.GET); + requestContext.setHeaderParam("Accept", "application/json, */*;q=0.8") + + // Query Params + if (totalCount !== undefined) { + requestContext.setQueryParam("totalCount", ObjectSerializer.serialize(totalCount, "boolean", "")); + } + + // Query Params + if (cursor !== undefined) { + requestContext.setQueryParam("cursor", ObjectSerializer.serialize(cursor, "string", "")); + } + + // Query Params + if (limit !== undefined) { + requestContext.setQueryParam("limit", ObjectSerializer.serialize(limit, "number", "int32")); + } + + + let authMethod: SecurityAuthentication | undefined; + // Apply auth methods + authMethod = _config.authMethods["bearerAuth"] + if (authMethod?.applySecurityAuthentication) { + await authMethod?.applySecurityAuthentication(requestContext); + } + + const defaultAuth: SecurityAuthentication | undefined = _config?.authMethods?.default + if (defaultAuth?.applySecurityAuthentication) { + await defaultAuth?.applySecurityAuthentication(requestContext); + } + + return requestContext; + } + + /** + * | ⚠️ This endpoint is currently in BETA | |--| Returns directly attached opportunities for a given Note. + * Get Opportunities attached to a Note + * @param noteId The id of the Note to get attached Opportunities + * @param totalCount Include total count of the collection in the pagination response + * @param cursor Cursor for the next or previous page + * @param limit Number of items to include in the page + */ + public async v2NotesNoteIdAttachedOpportunitiesGET(noteId: number, totalCount?: boolean, cursor?: string, limit?: number, _options?: Configuration): Promise { + let _config = _options || this.configuration; + + // verify required parameter 'noteId' is not null or undefined + if (noteId === null || noteId === undefined) { + throw new RequiredError("NotesApi", "v2NotesNoteIdAttachedOpportunitiesGET", "noteId"); + } + + + + + + // Path Params + const localVarPath = '/v2/notes/{noteId}/attached-opportunities' + .replace('{' + 'noteId' + '}', encodeURIComponent(String(noteId))); + + // Make Request Context + const requestContext = _config.baseServer.makeRequestContext(localVarPath, HttpMethod.GET); + requestContext.setHeaderParam("Accept", "application/json, */*;q=0.8") + + // Query Params + if (totalCount !== undefined) { + requestContext.setQueryParam("totalCount", ObjectSerializer.serialize(totalCount, "boolean", "")); + } + + // Query Params + if (cursor !== undefined) { + requestContext.setQueryParam("cursor", ObjectSerializer.serialize(cursor, "string", "")); + } + + // Query Params + if (limit !== undefined) { + requestContext.setQueryParam("limit", ObjectSerializer.serialize(limit, "number", "int32")); + } + + + let authMethod: SecurityAuthentication | undefined; + // Apply auth methods + authMethod = _config.authMethods["bearerAuth"] + if (authMethod?.applySecurityAuthentication) { + await authMethod?.applySecurityAuthentication(requestContext); + } + + const defaultAuth: SecurityAuthentication | undefined = _config?.authMethods?.default + if (defaultAuth?.applySecurityAuthentication) { + await defaultAuth?.applySecurityAuthentication(requestContext); + } + + return requestContext; + } + + /** + * | ⚠️ This endpoint is currently in BETA | |--| Returns directly attached persons for a given Note. + * Get Persons attached to a Note + * @param noteId The id of the Note to get attached Persons + * @param totalCount Include total count of the collection in the pagination response + * @param cursor Cursor for the next or previous page + * @param limit Number of items to include in the page + */ + public async v2NotesNoteIdAttachedPersonsGET(noteId: number, totalCount?: boolean, cursor?: string, limit?: number, _options?: Configuration): Promise { + let _config = _options || this.configuration; + + // verify required parameter 'noteId' is not null or undefined + if (noteId === null || noteId === undefined) { + throw new RequiredError("NotesApi", "v2NotesNoteIdAttachedPersonsGET", "noteId"); + } + + + + + + // Path Params + const localVarPath = '/v2/notes/{noteId}/attached-persons' + .replace('{' + 'noteId' + '}', encodeURIComponent(String(noteId))); + + // Make Request Context + const requestContext = _config.baseServer.makeRequestContext(localVarPath, HttpMethod.GET); + requestContext.setHeaderParam("Accept", "application/json, */*;q=0.8") + + // Query Params + if (totalCount !== undefined) { + requestContext.setQueryParam("totalCount", ObjectSerializer.serialize(totalCount, "boolean", "")); + } + + // Query Params + if (cursor !== undefined) { + requestContext.setQueryParam("cursor", ObjectSerializer.serialize(cursor, "string", "")); + } + + // Query Params + if (limit !== undefined) { + requestContext.setQueryParam("limit", ObjectSerializer.serialize(limit, "number", "int32")); + } + + + let authMethod: SecurityAuthentication | undefined; + // Apply auth methods + authMethod = _config.authMethods["bearerAuth"] + if (authMethod?.applySecurityAuthentication) { + await authMethod?.applySecurityAuthentication(requestContext); + } + + const defaultAuth: SecurityAuthentication | undefined = _config?.authMethods?.default + if (defaultAuth?.applySecurityAuthentication) { + await defaultAuth?.applySecurityAuthentication(requestContext); + } + + return requestContext; + } + + /** + * | ⚠️ This endpoint is currently in BETA | |--| Get a Note with a given id + * Get a single Note + * @param noteId The id of the Note + * @param includes Additional properties to include in the response + */ + public async v2NotesNoteIdGET(noteId: number, includes?: Set<'companiesPreview' | 'personsPreview' | 'opportunitiesPreview' | 'repliesCount'>, _options?: Configuration): Promise { + let _config = _options || this.configuration; + + // verify required parameter 'noteId' is not null or undefined + if (noteId === null || noteId === undefined) { + throw new RequiredError("NotesApi", "v2NotesNoteIdGET", "noteId"); + } + + + + // Path Params + const localVarPath = '/v2/notes/{noteId}' + .replace('{' + 'noteId' + '}', encodeURIComponent(String(noteId))); + + // Make Request Context + const requestContext = _config.baseServer.makeRequestContext(localVarPath, HttpMethod.GET); + requestContext.setHeaderParam("Accept", "application/json, */*;q=0.8") + + // Query Params + if (includes !== undefined) { + const serializedParams = ObjectSerializer.serialize(includes, "Set<'companiesPreview' | 'personsPreview' | 'opportunitiesPreview' | 'repliesCount'>", ""); + for (const serializedParam of serializedParams) { + requestContext.appendQueryParam("includes", serializedParam); + } + } + + + let authMethod: SecurityAuthentication | undefined; + // Apply auth methods + authMethod = _config.authMethods["bearerAuth"] + if (authMethod?.applySecurityAuthentication) { + await authMethod?.applySecurityAuthentication(requestContext); + } + + const defaultAuth: SecurityAuthentication | undefined = _config?.authMethods?.default + if (defaultAuth?.applySecurityAuthentication) { + await defaultAuth?.applySecurityAuthentication(requestContext); + } + + return requestContext; + } + + /** + * | ⚠️ This endpoint is currently in BETA | |--| This endpoint returns reply notes for a given note id. You can filter replies using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|---------------------------------| | `creator.id` | Filter notes by the creator of the note | `int32` | `=` | `creator.id=1` | | `createdAt` | Filter notes by when it was created | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-02-04T10:48:24Z` | | `updatedAt` | Filter notes by when it was updated | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-02-03T10:48:24Z`| + * Get replies for a Note + * @param noteId Note ID + * @param filter Filter options + * @param cursor Cursor for the next or previous page + * @param limit Number of items to include in the page + * @param totalCount Include total count of the collection in the pagination response + */ + public async v2NotesNoteIdRepliesGET(noteId: number, filter?: string, cursor?: string, limit?: number, totalCount?: boolean, _options?: Configuration): Promise { + let _config = _options || this.configuration; + + // verify required parameter 'noteId' is not null or undefined + if (noteId === null || noteId === undefined) { + throw new RequiredError("NotesApi", "v2NotesNoteIdRepliesGET", "noteId"); + } + + + + + + + // Path Params + const localVarPath = '/v2/notes/{noteId}/replies' + .replace('{' + 'noteId' + '}', encodeURIComponent(String(noteId))); + + // Make Request Context + const requestContext = _config.baseServer.makeRequestContext(localVarPath, HttpMethod.GET); + requestContext.setHeaderParam("Accept", "application/json, */*;q=0.8") + + // Query Params + if (filter !== undefined) { + requestContext.setQueryParam("filter", ObjectSerializer.serialize(filter, "string", "")); + } + + // Query Params + if (cursor !== undefined) { + requestContext.setQueryParam("cursor", ObjectSerializer.serialize(cursor, "string", "")); + } + + // Query Params + if (limit !== undefined) { + requestContext.setQueryParam("limit", ObjectSerializer.serialize(limit, "number", "int32")); + } + + // Query Params + if (totalCount !== undefined) { + requestContext.setQueryParam("totalCount", ObjectSerializer.serialize(totalCount, "boolean", "")); + } + + + let authMethod: SecurityAuthentication | undefined; + // Apply auth methods + authMethod = _config.authMethods["bearerAuth"] + if (authMethod?.applySecurityAuthentication) { + await authMethod?.applySecurityAuthentication(requestContext); + } + + const defaultAuth: SecurityAuthentication | undefined = _config?.authMethods?.default + if (defaultAuth?.applySecurityAuthentication) { + await defaultAuth?.applySecurityAuthentication(requestContext); + } + + return requestContext; + } + +} + +export class NotesApiResponseProcessor { + + /** + * Unwraps the actual response sent by the server from the response context and deserializes the response content + * to the expected objects + * + * @params response Response returned by the server for a request to v2NotesGET + * @throws ApiException if the response code was not in [200, 299] + */ + public async v2NotesGETWithHttpInfo(response: ResponseContext): Promise> { + const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); + if (isCodeInRange("200", response.httpStatusCode)) { + const body: NotesNotesPaged = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "NotesNotesPaged", "" + ) as NotesNotesPaged; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + if (isCodeInRange("400", response.httpStatusCode)) { + const body: Responses400 = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + } + if (isCodeInRange("404", response.httpStatusCode)) { + const body: NotFoundErrors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "NotFoundErrors", "" + ) as NotFoundErrors; + throw new ApiException(response.httpStatusCode, "Not Found", body, response.headers); + } + if (isCodeInRange("0", response.httpStatusCode)) { + const body: Errors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Errors", "" + ) as Errors; + throw new ApiException(response.httpStatusCode, "Errors", body, response.headers); + } + + // Work around for missing responses in specification, e.g. for petstore.yaml + if (response.httpStatusCode >= 200 && response.httpStatusCode <= 299) { + const body: NotesNotesPaged = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "NotesNotesPaged", "" + ) as NotesNotesPaged; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + + throw new ApiException(response.httpStatusCode, "Unknown API Status Code!", await response.getBodyAsAny(), response.headers); + } + + /** + * Unwraps the actual response sent by the server from the response context and deserializes the response content + * to the expected objects + * + * @params response Response returned by the server for a request to v2NotesNoteIdAttachedCompaniesGET + * @throws ApiException if the response code was not in [200, 299] + */ + public async v2NotesNoteIdAttachedCompaniesGETWithHttpInfo(response: ResponseContext): Promise> { + const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); + if (isCodeInRange("200", response.httpStatusCode)) { + const body: CompanyDataPaged = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "CompanyDataPaged", "" + ) as CompanyDataPaged; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + if (isCodeInRange("400", response.httpStatusCode)) { + const body: Responses400 = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + } + if (isCodeInRange("404", response.httpStatusCode)) { + const body: NotFoundErrors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "NotFoundErrors", "" + ) as NotFoundErrors; + throw new ApiException(response.httpStatusCode, "Not Found", body, response.headers); + } + if (isCodeInRange("0", response.httpStatusCode)) { + const body: Errors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Errors", "" + ) as Errors; + throw new ApiException(response.httpStatusCode, "Errors", body, response.headers); + } + + // Work around for missing responses in specification, e.g. for petstore.yaml + if (response.httpStatusCode >= 200 && response.httpStatusCode <= 299) { + const body: CompanyDataPaged = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "CompanyDataPaged", "" + ) as CompanyDataPaged; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + + throw new ApiException(response.httpStatusCode, "Unknown API Status Code!", await response.getBodyAsAny(), response.headers); + } + + /** + * Unwraps the actual response sent by the server from the response context and deserializes the response content + * to the expected objects + * + * @params response Response returned by the server for a request to v2NotesNoteIdAttachedOpportunitiesGET + * @throws ApiException if the response code was not in [200, 299] + */ + public async v2NotesNoteIdAttachedOpportunitiesGETWithHttpInfo(response: ResponseContext): Promise> { + const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); + if (isCodeInRange("200", response.httpStatusCode)) { + const body: OpportunityPaged = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "OpportunityPaged", "" + ) as OpportunityPaged; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + if (isCodeInRange("400", response.httpStatusCode)) { + const body: Responses400 = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + } + if (isCodeInRange("404", response.httpStatusCode)) { + const body: NotFoundErrors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "NotFoundErrors", "" + ) as NotFoundErrors; + throw new ApiException(response.httpStatusCode, "Not Found", body, response.headers); + } + if (isCodeInRange("0", response.httpStatusCode)) { + const body: Errors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Errors", "" + ) as Errors; + throw new ApiException(response.httpStatusCode, "Errors", body, response.headers); + } + + // Work around for missing responses in specification, e.g. for petstore.yaml + if (response.httpStatusCode >= 200 && response.httpStatusCode <= 299) { + const body: OpportunityPaged = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "OpportunityPaged", "" + ) as OpportunityPaged; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + + throw new ApiException(response.httpStatusCode, "Unknown API Status Code!", await response.getBodyAsAny(), response.headers); + } + + /** + * Unwraps the actual response sent by the server from the response context and deserializes the response content + * to the expected objects + * + * @params response Response returned by the server for a request to v2NotesNoteIdAttachedPersonsGET + * @throws ApiException if the response code was not in [200, 299] + */ + public async v2NotesNoteIdAttachedPersonsGETWithHttpInfo(response: ResponseContext): Promise> { + const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); + if (isCodeInRange("200", response.httpStatusCode)) { + const body: PersonDataPaged = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "PersonDataPaged", "" + ) as PersonDataPaged; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + if (isCodeInRange("400", response.httpStatusCode)) { + const body: Responses400 = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + } + if (isCodeInRange("404", response.httpStatusCode)) { + const body: NotFoundErrors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "NotFoundErrors", "" + ) as NotFoundErrors; + throw new ApiException(response.httpStatusCode, "Not Found", body, response.headers); + } + if (isCodeInRange("0", response.httpStatusCode)) { + const body: Errors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Errors", "" + ) as Errors; + throw new ApiException(response.httpStatusCode, "Errors", body, response.headers); + } + + // Work around for missing responses in specification, e.g. for petstore.yaml + if (response.httpStatusCode >= 200 && response.httpStatusCode <= 299) { + const body: PersonDataPaged = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "PersonDataPaged", "" + ) as PersonDataPaged; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + + throw new ApiException(response.httpStatusCode, "Unknown API Status Code!", await response.getBodyAsAny(), response.headers); + } + + /** + * Unwraps the actual response sent by the server from the response context and deserializes the response content + * to the expected objects + * + * @params response Response returned by the server for a request to v2NotesNoteIdGET + * @throws ApiException if the response code was not in [200, 299] + */ + public async v2NotesNoteIdGETWithHttpInfo(response: ResponseContext): Promise> { + const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); + if (isCodeInRange("200", response.httpStatusCode)) { + const body: NotesNote = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "NotesNote", "" + ) as NotesNote; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + if (isCodeInRange("400", response.httpStatusCode)) { + const body: Responses400 = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + } + if (isCodeInRange("404", response.httpStatusCode)) { + const body: NotFoundErrors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "NotFoundErrors", "" + ) as NotFoundErrors; + throw new ApiException(response.httpStatusCode, "Not Found", body, response.headers); + } + if (isCodeInRange("0", response.httpStatusCode)) { + const body: Errors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Errors", "" + ) as Errors; + throw new ApiException(response.httpStatusCode, "Errors", body, response.headers); + } + + // Work around for missing responses in specification, e.g. for petstore.yaml + if (response.httpStatusCode >= 200 && response.httpStatusCode <= 299) { + const body: NotesNote = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "NotesNote", "" + ) as NotesNote; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + + throw new ApiException(response.httpStatusCode, "Unknown API Status Code!", await response.getBodyAsAny(), response.headers); + } + + /** + * Unwraps the actual response sent by the server from the response context and deserializes the response content + * to the expected objects + * + * @params response Response returned by the server for a request to v2NotesNoteIdRepliesGET + * @throws ApiException if the response code was not in [200, 299] + */ + public async v2NotesNoteIdRepliesGETWithHttpInfo(response: ResponseContext): Promise> { + const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); + if (isCodeInRange("200", response.httpStatusCode)) { + const body: NotesRepliesPaged = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "NotesRepliesPaged", "" + ) as NotesRepliesPaged; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + if (isCodeInRange("400", response.httpStatusCode)) { + const body: Responses400 = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + } + if (isCodeInRange("404", response.httpStatusCode)) { + const body: NotFoundErrors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "NotFoundErrors", "" + ) as NotFoundErrors; + throw new ApiException(response.httpStatusCode, "Not Found", body, response.headers); + } + if (isCodeInRange("0", response.httpStatusCode)) { + const body: Errors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Errors", "" + ) as Errors; + throw new ApiException(response.httpStatusCode, "Errors", body, response.headers); + } + + // Work around for missing responses in specification, e.g. for petstore.yaml + if (response.httpStatusCode >= 200 && response.httpStatusCode <= 299) { + const body: NotesRepliesPaged = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "NotesRepliesPaged", "" + ) as NotesRepliesPaged; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + + throw new ApiException(response.httpStatusCode, "Unknown API Status Code!", await response.getBodyAsAny(), response.headers); + } + +} diff --git a/src/v2/generated/apis/OpportunitiesApi.ts b/src/v2/generated/apis/OpportunitiesApi.ts index 6d9b2f3..fbbbcd7 100644 --- a/src/v2/generated/apis/OpportunitiesApi.ts +++ b/src/v2/generated/apis/OpportunitiesApi.ts @@ -10,10 +10,11 @@ import {SecurityAuthentication} from '../auth/auth.ts'; import { AuthorizationErrors } from '../models/AuthorizationErrors.ts'; import { Errors } from '../models/Errors.ts'; -import { InlineObject } from '../models/InlineObject.ts'; import { NotFoundErrors } from '../models/NotFoundErrors.ts'; +import { NotesNotesPaged } from '../models/NotesNotesPaged.ts'; import { Opportunity } from '../models/Opportunity.ts'; import { OpportunityPaged } from '../models/OpportunityPaged.ts'; +import { Responses400 } from '../models/Responses400.ts'; /** * no description @@ -27,7 +28,7 @@ export class OpportunitiesApiRequestFactory extends BaseAPIRequestFactory { * @param limit Number of items to include in the page * @param ids Opportunity IDs */ - public async getV2Opportunities(cursor?: string, limit?: number, ids?: Array, _options?: Configuration): Promise { + public async v2OpportunitiesGET(cursor?: string, limit?: number, ids?: Array, _options?: Configuration): Promise { let _config = _options || this.configuration; @@ -77,26 +78,92 @@ export class OpportunitiesApiRequestFactory extends BaseAPIRequestFactory { /** * Returns basic information but **not** field data on the requested Opportunity. To access field data on Opportunities, use the `/lists/{list_id}/list-entries` or the `/v2/lists/{list_id}/saved-views/{view_id}/list-entries` GET endpoint. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). * Get a single Opportunity - * @param id Opportunity ID + * @param opportunityId Opportunity ID */ - public async getV2OpportunitiesId(id: number, _options?: Configuration): Promise { + public async v2OpportunitiesOpportunityIdGET(opportunityId: number, _options?: Configuration): Promise { let _config = _options || this.configuration; - // verify required parameter 'id' is not null or undefined - if (id === null || id === undefined) { - throw new RequiredError("OpportunitiesApi", "getV2OpportunitiesId", "id"); + // verify required parameter 'opportunityId' is not null or undefined + if (opportunityId === null || opportunityId === undefined) { + throw new RequiredError("OpportunitiesApi", "v2OpportunitiesOpportunityIdGET", "opportunityId"); } // Path Params - const localVarPath = '/v2/opportunities/{id}' - .replace('{' + 'id' + '}', encodeURIComponent(String(id))); + const localVarPath = '/v2/opportunities/{opportunityId}' + .replace('{' + 'opportunityId' + '}', encodeURIComponent(String(opportunityId))); // Make Request Context const requestContext = _config.baseServer.makeRequestContext(localVarPath, HttpMethod.GET); requestContext.setHeaderParam("Accept", "application/json, */*;q=0.8") + let authMethod: SecurityAuthentication | undefined; + // Apply auth methods + authMethod = _config.authMethods["bearerAuth"] + if (authMethod?.applySecurityAuthentication) { + await authMethod?.applySecurityAuthentication(requestContext); + } + + const defaultAuth: SecurityAuthentication | undefined = _config?.authMethods?.default + if (defaultAuth?.applySecurityAuthentication) { + await defaultAuth?.applySecurityAuthentication(requestContext); + } + + return requestContext; + } + + /** + * | ⚠️ This endpoint is currently in BETA | |--| Returns Notes for a given Opportunity which includes directly attached notes and those attached to persons on this Opportunity. You can filter notes using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|---------------------------------| | `creator.id` | Filter notes by the creator of the note | `int32` | `=` | `creator.id=1` | | `createdAt` | Filter notes by when it was created | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-02-04T10:48:24Z` | | `updatedAt` | Filter notes by when it was updated | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-02-03T10:48:24Z`| + * Get Notes for an Opportunity + * @param opportunityId Opportunity ID + * @param filter Filter options + * @param cursor Cursor for the next or previous page + * @param limit Number of items to include in the page + * @param totalCount Include total count of the collection in the pagination response + */ + public async v2OpportunitiesOpportunityIdNotesGET(opportunityId: number, filter?: string, cursor?: string, limit?: number, totalCount?: boolean, _options?: Configuration): Promise { + let _config = _options || this.configuration; + + // verify required parameter 'opportunityId' is not null or undefined + if (opportunityId === null || opportunityId === undefined) { + throw new RequiredError("OpportunitiesApi", "v2OpportunitiesOpportunityIdNotesGET", "opportunityId"); + } + + + + + + + // Path Params + const localVarPath = '/v2/opportunities/{opportunityId}/notes' + .replace('{' + 'opportunityId' + '}', encodeURIComponent(String(opportunityId))); + + // Make Request Context + const requestContext = _config.baseServer.makeRequestContext(localVarPath, HttpMethod.GET); + requestContext.setHeaderParam("Accept", "application/json, */*;q=0.8") + + // Query Params + if (filter !== undefined) { + requestContext.setQueryParam("filter", ObjectSerializer.serialize(filter, "string", "")); + } + + // Query Params + if (cursor !== undefined) { + requestContext.setQueryParam("cursor", ObjectSerializer.serialize(cursor, "string", "")); + } + + // Query Params + if (limit !== undefined) { + requestContext.setQueryParam("limit", ObjectSerializer.serialize(limit, "number", "int32")); + } + + // Query Params + if (totalCount !== undefined) { + requestContext.setQueryParam("totalCount", ObjectSerializer.serialize(totalCount, "boolean", "")); + } + + let authMethod: SecurityAuthentication | undefined; // Apply auth methods authMethod = _config.authMethods["bearerAuth"] @@ -120,10 +187,10 @@ export class OpportunitiesApiResponseProcessor { * Unwraps the actual response sent by the server from the response context and deserializes the response content * to the expected objects * - * @params response Response returned by the server for a request to getV2Opportunities + * @params response Response returned by the server for a request to v2OpportunitiesGET * @throws ApiException if the response code was not in [200, 299] */ - public async getV2OpportunitiesWithHttpInfo(response: ResponseContext): Promise> { + public async v2OpportunitiesGETWithHttpInfo(response: ResponseContext): Promise> { const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); if (isCodeInRange("200", response.httpStatusCode)) { const body: OpportunityPaged = ObjectSerializer.deserialize( @@ -133,11 +200,11 @@ export class OpportunitiesApiResponseProcessor { return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); } if (isCodeInRange("400", response.httpStatusCode)) { - const body: InlineObject = ObjectSerializer.deserialize( + const body: Responses400 = ObjectSerializer.deserialize( ObjectSerializer.parse(await response.body.text(), contentType), - "InlineObject", "" - ) as InlineObject; - throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); } if (isCodeInRange("403", response.httpStatusCode)) { const body: AuthorizationErrors = ObjectSerializer.deserialize( @@ -177,10 +244,10 @@ export class OpportunitiesApiResponseProcessor { * Unwraps the actual response sent by the server from the response context and deserializes the response content * to the expected objects * - * @params response Response returned by the server for a request to getV2OpportunitiesId + * @params response Response returned by the server for a request to v2OpportunitiesOpportunityIdGET * @throws ApiException if the response code was not in [200, 299] */ - public async getV2OpportunitiesIdWithHttpInfo(response: ResponseContext): Promise> { + public async v2OpportunitiesOpportunityIdGETWithHttpInfo(response: ResponseContext): Promise> { const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); if (isCodeInRange("200", response.httpStatusCode)) { const body: Opportunity = ObjectSerializer.deserialize( @@ -190,11 +257,11 @@ export class OpportunitiesApiResponseProcessor { return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); } if (isCodeInRange("400", response.httpStatusCode)) { - const body: InlineObject = ObjectSerializer.deserialize( + const body: Responses400 = ObjectSerializer.deserialize( ObjectSerializer.parse(await response.body.text(), contentType), - "InlineObject", "" - ) as InlineObject; - throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); } if (isCodeInRange("403", response.httpStatusCode)) { const body: AuthorizationErrors = ObjectSerializer.deserialize( @@ -230,4 +297,54 @@ export class OpportunitiesApiResponseProcessor { throw new ApiException(response.httpStatusCode, "Unknown API Status Code!", await response.getBodyAsAny(), response.headers); } + /** + * Unwraps the actual response sent by the server from the response context and deserializes the response content + * to the expected objects + * + * @params response Response returned by the server for a request to v2OpportunitiesOpportunityIdNotesGET + * @throws ApiException if the response code was not in [200, 299] + */ + public async v2OpportunitiesOpportunityIdNotesGETWithHttpInfo(response: ResponseContext): Promise> { + const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); + if (isCodeInRange("200", response.httpStatusCode)) { + const body: NotesNotesPaged = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "NotesNotesPaged", "" + ) as NotesNotesPaged; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + if (isCodeInRange("400", response.httpStatusCode)) { + const body: Responses400 = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + } + if (isCodeInRange("404", response.httpStatusCode)) { + const body: NotFoundErrors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "NotFoundErrors", "" + ) as NotFoundErrors; + throw new ApiException(response.httpStatusCode, "Not Found", body, response.headers); + } + if (isCodeInRange("0", response.httpStatusCode)) { + const body: Errors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Errors", "" + ) as Errors; + throw new ApiException(response.httpStatusCode, "Errors", body, response.headers); + } + + // Work around for missing responses in specification, e.g. for petstore.yaml + if (response.httpStatusCode >= 200 && response.httpStatusCode <= 299) { + const body: NotesNotesPaged = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "NotesNotesPaged", "" + ) as NotesNotesPaged; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + + throw new ApiException(response.httpStatusCode, "Unknown API Status Code!", await response.getBodyAsAny(), response.headers); + } + } diff --git a/src/v2/generated/apis/PersonMergesApi.ts b/src/v2/generated/apis/PersonMergesApi.ts new file mode 100644 index 0000000..ff65553 --- /dev/null +++ b/src/v2/generated/apis/PersonMergesApi.ts @@ -0,0 +1,521 @@ +// TODO: better import syntax? +import {BaseAPIRequestFactory, RequiredError, COLLECTION_FORMATS} from './baseapi.ts'; +import {Configuration} from '../configuration.ts'; +import {RequestContext, HttpMethod, ResponseContext, HttpFile, HttpInfo} from '../http/http.ts'; +import {ObjectSerializer} from '../models/ObjectSerializer.ts'; +import {ApiException} from './exception.ts'; +import {canConsumeForm, isCodeInRange} from '../util.ts'; +import {SecurityAuthentication} from '../auth/auth.ts'; + + +import { AuthorizationErrors } from '../models/AuthorizationErrors.ts'; +import { Errors } from '../models/Errors.ts'; +import { NotFoundErrors } from '../models/NotFoundErrors.ts'; +import { PersonMergeRequest } from '../models/PersonMergeRequest.ts'; +import { PersonMergeResponse } from '../models/PersonMergeResponse.ts'; +import { PersonMergeState } from '../models/PersonMergeState.ts'; +import { PersonMergeStatePaged } from '../models/PersonMergeStatePaged.ts'; +import { PersonMergeTask } from '../models/PersonMergeTask.ts'; +import { PersonMergeTaskPaged } from '../models/PersonMergeTaskPaged.ts'; +import { Responses400 } from '../models/Responses400.ts'; + +/** + * no description + */ +export class PersonMergesApiRequestFactory extends BaseAPIRequestFactory { + + /** + * Retrieve paginated person merges for the organization. Returns all person merges initiated by users in your organization, including their current status, the persons involved, and merge details. You can filter person merges using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties: | Property | Type | Operators | Values | Examples | |----------|------|-----------|--------|----------| | `status` | `enum` | `=` | `in-progress`, `success`, `failed` | `status=failed` | | `taskId` | `string` | `=` | | `taskId=789e0123-e45b-67c8-d901-234567890123` | Person merges are returned in reverse chronological order (most recent first). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get All Person Merges + * @param cursor Cursor for the next or previous page + * @param limit Number of items to include in the page + * @param filter Filter person merges using Affinity Filtering Language + */ + public async v2PersonMergesGET(cursor?: string, limit?: number, filter?: string, _options?: Configuration): Promise { + let _config = _options || this.configuration; + + + + + // Path Params + const localVarPath = '/v2/person-merges'; + + // Make Request Context + const requestContext = _config.baseServer.makeRequestContext(localVarPath, HttpMethod.GET); + requestContext.setHeaderParam("Accept", "application/json, */*;q=0.8") + + // Query Params + if (cursor !== undefined) { + requestContext.setQueryParam("cursor", ObjectSerializer.serialize(cursor, "string", "")); + } + + // Query Params + if (limit !== undefined) { + requestContext.setQueryParam("limit", ObjectSerializer.serialize(limit, "number", "int32")); + } + + // Query Params + if (filter !== undefined) { + requestContext.setQueryParam("filter", ObjectSerializer.serialize(filter, "string", "")); + } + + + let authMethod: SecurityAuthentication | undefined; + // Apply auth methods + authMethod = _config.authMethods["bearerAuth"] + if (authMethod?.applySecurityAuthentication) { + await authMethod?.applySecurityAuthentication(requestContext); + } + + const defaultAuth: SecurityAuthentication | undefined = _config?.authMethods?.default + if (defaultAuth?.applySecurityAuthentication) { + await defaultAuth?.applySecurityAuthentication(requestContext); + } + + return requestContext; + } + + /** + * Retrieve the status and details of a specific person merge. Returns information about the person merge including its current status, the persons involved, timestamps, and any error information if the merge failed. The `mergeId` can be obtained from the response of the [Get All Person Merges](#tag/personMerges/operation/v2_person-merges__GET) endpoint, or by filtering person merges by task ID using `/v2/person-merges?filter=taskId={taskId}` after initiating a merge. Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get Person Merge + * @param mergeId Person merge ID + */ + public async v2PersonMergesMergeIdGET(mergeId: number, _options?: Configuration): Promise { + let _config = _options || this.configuration; + + // verify required parameter 'mergeId' is not null or undefined + if (mergeId === null || mergeId === undefined) { + throw new RequiredError("PersonMergesApi", "v2PersonMergesMergeIdGET", "mergeId"); + } + + + // Path Params + const localVarPath = '/v2/person-merges/{mergeId}' + .replace('{' + 'mergeId' + '}', encodeURIComponent(String(mergeId))); + + // Make Request Context + const requestContext = _config.baseServer.makeRequestContext(localVarPath, HttpMethod.GET); + requestContext.setHeaderParam("Accept", "application/json, */*;q=0.8") + + + let authMethod: SecurityAuthentication | undefined; + // Apply auth methods + authMethod = _config.authMethods["bearerAuth"] + if (authMethod?.applySecurityAuthentication) { + await authMethod?.applySecurityAuthentication(requestContext); + } + + const defaultAuth: SecurityAuthentication | undefined = _config?.authMethods?.default + if (defaultAuth?.applySecurityAuthentication) { + await defaultAuth?.applySecurityAuthentication(requestContext); + } + + return requestContext; + } + + /** + * Initiate a person merge to combine a duplicate person profile into a primary person profile. This is an asynchronous process that will merge all data from the duplicate person into the primary person. Once the merge is initiated, you can track its progress using the returned [task URL](#tag/personMerges/operation/v2_tasks_person-merges_taskId__GET). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Initiate Person Merge + * @param personMergeRequest + */ + public async v2PersonMergesPOST(personMergeRequest: PersonMergeRequest, _options?: Configuration): Promise { + let _config = _options || this.configuration; + + // verify required parameter 'personMergeRequest' is not null or undefined + if (personMergeRequest === null || personMergeRequest === undefined) { + throw new RequiredError("PersonMergesApi", "v2PersonMergesPOST", "personMergeRequest"); + } + + + // Path Params + const localVarPath = '/v2/person-merges'; + + // Make Request Context + const requestContext = _config.baseServer.makeRequestContext(localVarPath, HttpMethod.POST); + requestContext.setHeaderParam("Accept", "application/json, */*;q=0.8") + + + // Body Params + const contentType = ObjectSerializer.getPreferredMediaType([ + "application/json" + ]); + requestContext.setHeaderParam("Content-Type", contentType); + const serializedBody = ObjectSerializer.stringify( + ObjectSerializer.serialize(personMergeRequest, "PersonMergeRequest", ""), + contentType + ); + requestContext.setBody(serializedBody); + + let authMethod: SecurityAuthentication | undefined; + // Apply auth methods + authMethod = _config.authMethods["bearerAuth"] + if (authMethod?.applySecurityAuthentication) { + await authMethod?.applySecurityAuthentication(requestContext); + } + + const defaultAuth: SecurityAuthentication | undefined = _config?.authMethods?.default + if (defaultAuth?.applySecurityAuthentication) { + await defaultAuth?.applySecurityAuthentication(requestContext); + } + + return requestContext; + } + + /** + * Retrieve paginated person merge tasks for the organization. Returns all merge tasks initiated by users in your organization, including their current status, the persons involved, and task details. You can filter tasks using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties: | Property | Type | Operators | Values | Examples | |----------|------|-----------|--------|----------| | `status` | `enum` | `=` | `in-progress`, `success`, `failed` | `status=failed` | Tasks are returned in reverse chronological order (most recent first). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get All Person Merge Tasks + * @param cursor Cursor for the next or previous page + * @param limit Number of items to include in the page + * @param filter Filter tasks using Affinity Filtering Language + */ + public async v2TasksPersonMergesGET(cursor?: string, limit?: number, filter?: string, _options?: Configuration): Promise { + let _config = _options || this.configuration; + + + + + // Path Params + const localVarPath = '/v2/tasks/person-merges'; + + // Make Request Context + const requestContext = _config.baseServer.makeRequestContext(localVarPath, HttpMethod.GET); + requestContext.setHeaderParam("Accept", "application/json, */*;q=0.8") + + // Query Params + if (cursor !== undefined) { + requestContext.setQueryParam("cursor", ObjectSerializer.serialize(cursor, "string", "")); + } + + // Query Params + if (limit !== undefined) { + requestContext.setQueryParam("limit", ObjectSerializer.serialize(limit, "number", "int32")); + } + + // Query Params + if (filter !== undefined) { + requestContext.setQueryParam("filter", ObjectSerializer.serialize(filter, "string", "")); + } + + + let authMethod: SecurityAuthentication | undefined; + // Apply auth methods + authMethod = _config.authMethods["bearerAuth"] + if (authMethod?.applySecurityAuthentication) { + await authMethod?.applySecurityAuthentication(requestContext); + } + + const defaultAuth: SecurityAuthentication | undefined = _config?.authMethods?.default + if (defaultAuth?.applySecurityAuthentication) { + await defaultAuth?.applySecurityAuthentication(requestContext); + } + + return requestContext; + } + + /** + * Retrieve the status and details of a specific task for person merges. Returns information about the person merges for a specific task including its overall status, number of merges in-progress, completed, and failed. Detailed information about individual merges for this task can be found by querying: `/v2/person-merges?filter=taskId={taskId}` See [Person Merges](#tag/personMerges/operation/v2_person-merges__GET) for more details. Task statuses: - `in-progress`: The merge task is currently being processed. - `success`: The merge task completed successfully. - `failed`: The merge task failed. Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get Person Merge Task + * @param taskId Person merge task ID + */ + public async v2TasksPersonMergesTaskIdGET(taskId: string, _options?: Configuration): Promise { + let _config = _options || this.configuration; + + // verify required parameter 'taskId' is not null or undefined + if (taskId === null || taskId === undefined) { + throw new RequiredError("PersonMergesApi", "v2TasksPersonMergesTaskIdGET", "taskId"); + } + + + // Path Params + const localVarPath = '/v2/tasks/person-merges/{taskId}' + .replace('{' + 'taskId' + '}', encodeURIComponent(String(taskId))); + + // Make Request Context + const requestContext = _config.baseServer.makeRequestContext(localVarPath, HttpMethod.GET); + requestContext.setHeaderParam("Accept", "application/json, */*;q=0.8") + + + let authMethod: SecurityAuthentication | undefined; + // Apply auth methods + authMethod = _config.authMethods["bearerAuth"] + if (authMethod?.applySecurityAuthentication) { + await authMethod?.applySecurityAuthentication(requestContext); + } + + const defaultAuth: SecurityAuthentication | undefined = _config?.authMethods?.default + if (defaultAuth?.applySecurityAuthentication) { + await defaultAuth?.applySecurityAuthentication(requestContext); + } + + return requestContext; + } + +} + +export class PersonMergesApiResponseProcessor { + + /** + * Unwraps the actual response sent by the server from the response context and deserializes the response content + * to the expected objects + * + * @params response Response returned by the server for a request to v2PersonMergesGET + * @throws ApiException if the response code was not in [200, 299] + */ + public async v2PersonMergesGETWithHttpInfo(response: ResponseContext): Promise> { + const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); + if (isCodeInRange("200", response.httpStatusCode)) { + const body: PersonMergeStatePaged = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "PersonMergeStatePaged", "" + ) as PersonMergeStatePaged; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + if (isCodeInRange("400", response.httpStatusCode)) { + const body: Responses400 = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + } + if (isCodeInRange("403", response.httpStatusCode)) { + const body: AuthorizationErrors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "AuthorizationErrors", "" + ) as AuthorizationErrors; + throw new ApiException(response.httpStatusCode, "Forbidden", body, response.headers); + } + if (isCodeInRange("0", response.httpStatusCode)) { + const body: Errors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Errors", "" + ) as Errors; + throw new ApiException(response.httpStatusCode, "Errors", body, response.headers); + } + + // Work around for missing responses in specification, e.g. for petstore.yaml + if (response.httpStatusCode >= 200 && response.httpStatusCode <= 299) { + const body: PersonMergeStatePaged = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "PersonMergeStatePaged", "" + ) as PersonMergeStatePaged; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + + throw new ApiException(response.httpStatusCode, "Unknown API Status Code!", await response.getBodyAsAny(), response.headers); + } + + /** + * Unwraps the actual response sent by the server from the response context and deserializes the response content + * to the expected objects + * + * @params response Response returned by the server for a request to v2PersonMergesMergeIdGET + * @throws ApiException if the response code was not in [200, 299] + */ + public async v2PersonMergesMergeIdGETWithHttpInfo(response: ResponseContext): Promise> { + const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); + if (isCodeInRange("200", response.httpStatusCode)) { + const body: PersonMergeState = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "PersonMergeState", "" + ) as PersonMergeState; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + if (isCodeInRange("400", response.httpStatusCode)) { + const body: Responses400 = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + } + if (isCodeInRange("403", response.httpStatusCode)) { + const body: AuthorizationErrors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "AuthorizationErrors", "" + ) as AuthorizationErrors; + throw new ApiException(response.httpStatusCode, "Forbidden", body, response.headers); + } + if (isCodeInRange("404", response.httpStatusCode)) { + const body: NotFoundErrors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "NotFoundErrors", "" + ) as NotFoundErrors; + throw new ApiException(response.httpStatusCode, "Not Found", body, response.headers); + } + if (isCodeInRange("0", response.httpStatusCode)) { + const body: Errors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Errors", "" + ) as Errors; + throw new ApiException(response.httpStatusCode, "Errors", body, response.headers); + } + + // Work around for missing responses in specification, e.g. for petstore.yaml + if (response.httpStatusCode >= 200 && response.httpStatusCode <= 299) { + const body: PersonMergeState = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "PersonMergeState", "" + ) as PersonMergeState; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + + throw new ApiException(response.httpStatusCode, "Unknown API Status Code!", await response.getBodyAsAny(), response.headers); + } + + /** + * Unwraps the actual response sent by the server from the response context and deserializes the response content + * to the expected objects + * + * @params response Response returned by the server for a request to v2PersonMergesPOST + * @throws ApiException if the response code was not in [200, 299] + */ + public async v2PersonMergesPOSTWithHttpInfo(response: ResponseContext): Promise> { + const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); + if (isCodeInRange("202", response.httpStatusCode)) { + const body: PersonMergeResponse = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "PersonMergeResponse", "" + ) as PersonMergeResponse; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + if (isCodeInRange("400", response.httpStatusCode)) { + const body: Responses400 = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + } + if (isCodeInRange("403", response.httpStatusCode)) { + const body: AuthorizationErrors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "AuthorizationErrors", "" + ) as AuthorizationErrors; + throw new ApiException(response.httpStatusCode, "Forbidden", body, response.headers); + } + if (isCodeInRange("0", response.httpStatusCode)) { + const body: Errors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Errors", "" + ) as Errors; + throw new ApiException(response.httpStatusCode, "Errors", body, response.headers); + } + + // Work around for missing responses in specification, e.g. for petstore.yaml + if (response.httpStatusCode >= 200 && response.httpStatusCode <= 299) { + const body: PersonMergeResponse = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "PersonMergeResponse", "" + ) as PersonMergeResponse; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + + throw new ApiException(response.httpStatusCode, "Unknown API Status Code!", await response.getBodyAsAny(), response.headers); + } + + /** + * Unwraps the actual response sent by the server from the response context and deserializes the response content + * to the expected objects + * + * @params response Response returned by the server for a request to v2TasksPersonMergesGET + * @throws ApiException if the response code was not in [200, 299] + */ + public async v2TasksPersonMergesGETWithHttpInfo(response: ResponseContext): Promise> { + const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); + if (isCodeInRange("200", response.httpStatusCode)) { + const body: PersonMergeTaskPaged = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "PersonMergeTaskPaged", "" + ) as PersonMergeTaskPaged; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + if (isCodeInRange("400", response.httpStatusCode)) { + const body: Responses400 = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + } + if (isCodeInRange("403", response.httpStatusCode)) { + const body: AuthorizationErrors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "AuthorizationErrors", "" + ) as AuthorizationErrors; + throw new ApiException(response.httpStatusCode, "Forbidden", body, response.headers); + } + if (isCodeInRange("0", response.httpStatusCode)) { + const body: Errors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Errors", "" + ) as Errors; + throw new ApiException(response.httpStatusCode, "Errors", body, response.headers); + } + + // Work around for missing responses in specification, e.g. for petstore.yaml + if (response.httpStatusCode >= 200 && response.httpStatusCode <= 299) { + const body: PersonMergeTaskPaged = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "PersonMergeTaskPaged", "" + ) as PersonMergeTaskPaged; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + + throw new ApiException(response.httpStatusCode, "Unknown API Status Code!", await response.getBodyAsAny(), response.headers); + } + + /** + * Unwraps the actual response sent by the server from the response context and deserializes the response content + * to the expected objects + * + * @params response Response returned by the server for a request to v2TasksPersonMergesTaskIdGET + * @throws ApiException if the response code was not in [200, 299] + */ + public async v2TasksPersonMergesTaskIdGETWithHttpInfo(response: ResponseContext): Promise> { + const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); + if (isCodeInRange("200", response.httpStatusCode)) { + const body: PersonMergeTask = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "PersonMergeTask", "" + ) as PersonMergeTask; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + if (isCodeInRange("400", response.httpStatusCode)) { + const body: Responses400 = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + } + if (isCodeInRange("403", response.httpStatusCode)) { + const body: AuthorizationErrors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "AuthorizationErrors", "" + ) as AuthorizationErrors; + throw new ApiException(response.httpStatusCode, "Forbidden", body, response.headers); + } + if (isCodeInRange("404", response.httpStatusCode)) { + const body: NotFoundErrors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "NotFoundErrors", "" + ) as NotFoundErrors; + throw new ApiException(response.httpStatusCode, "Not Found", body, response.headers); + } + if (isCodeInRange("0", response.httpStatusCode)) { + const body: Errors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Errors", "" + ) as Errors; + throw new ApiException(response.httpStatusCode, "Errors", body, response.headers); + } + + // Work around for missing responses in specification, e.g. for petstore.yaml + if (response.httpStatusCode >= 200 && response.httpStatusCode <= 299) { + const body: PersonMergeTask = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "PersonMergeTask", "" + ) as PersonMergeTask; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + + throw new ApiException(response.httpStatusCode, "Unknown API Status Code!", await response.getBodyAsAny(), response.headers); + } + +} diff --git a/src/v2/generated/apis/PersonsApi.ts b/src/v2/generated/apis/PersonsApi.ts index 704f304..8b08910 100644 --- a/src/v2/generated/apis/PersonsApi.ts +++ b/src/v2/generated/apis/PersonsApi.ts @@ -11,18 +11,63 @@ import {SecurityAuthentication} from '../auth/auth.ts'; import { AuthorizationErrors } from '../models/AuthorizationErrors.ts'; import { Errors } from '../models/Errors.ts'; import { FieldMetadataPaged } from '../models/FieldMetadataPaged.ts'; -import { InlineObject } from '../models/InlineObject.ts'; import { ListEntryPaged } from '../models/ListEntryPaged.ts'; import { ListPaged } from '../models/ListPaged.ts'; import { NotFoundErrors } from '../models/NotFoundErrors.ts'; +import { NotesNotesPaged } from '../models/NotesNotesPaged.ts'; import { Person } from '../models/Person.ts'; import { PersonPaged } from '../models/PersonPaged.ts'; +import { Responses400 } from '../models/Responses400.ts'; /** * no description */ export class PersonsApiRequestFactory extends BaseAPIRequestFactory { + /** + * Returns metadata on non-list-specific Person Fields. Use the returned Field IDs to request field data from the GET `/v2/persons` and GET `/v2/persons/{id}` endpoints. + * Get metadata on Person Fields + * @param cursor Cursor for the next or previous page + * @param limit Number of items to include in the page + */ + public async v2PersonsFieldsGET(cursor?: string, limit?: number, _options?: Configuration): Promise { + let _config = _options || this.configuration; + + + + // Path Params + const localVarPath = '/v2/persons/fields'; + + // Make Request Context + const requestContext = _config.baseServer.makeRequestContext(localVarPath, HttpMethod.GET); + requestContext.setHeaderParam("Accept", "application/json, */*;q=0.8") + + // Query Params + if (cursor !== undefined) { + requestContext.setQueryParam("cursor", ObjectSerializer.serialize(cursor, "string", "")); + } + + // Query Params + if (limit !== undefined) { + requestContext.setQueryParam("limit", ObjectSerializer.serialize(limit, "number", "int32")); + } + + + let authMethod: SecurityAuthentication | undefined; + // Apply auth methods + authMethod = _config.authMethods["bearerAuth"] + if (authMethod?.applySecurityAuthentication) { + await authMethod?.applySecurityAuthentication(requestContext); + } + + const defaultAuth: SecurityAuthentication | undefined = _config?.authMethods?.default + if (defaultAuth?.applySecurityAuthentication) { + await defaultAuth?.applySecurityAuthentication(requestContext); + } + + return requestContext; + } + /** * Paginate through Persons in Affinity. Returns basic information and non-list-specific field data on each Person. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/persons/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Persons will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All People directory\" [permission](#section/Getting-Started/Permissions). * Get all Persons @@ -32,7 +77,7 @@ export class PersonsApiRequestFactory extends BaseAPIRequestFactory { * @param fieldIds Field IDs for which to return field data * @param fieldTypes Field Types for which to return field data */ - public async getV2Persons(cursor?: string, limit?: number, ids?: Array, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: Configuration): Promise { + public async v2PersonsGET(cursor?: string, limit?: number, ids?: Array, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: Configuration): Promise { let _config = _options || this.configuration; @@ -67,7 +112,7 @@ export class PersonsApiRequestFactory extends BaseAPIRequestFactory { // Query Params if (fieldIds !== undefined) { - const serializedParams = ObjectSerializer.serialize(fieldIds, "Array", "string"); + const serializedParams = ObjectSerializer.serialize(fieldIds, "Array", ""); for (const serializedParam of serializedParams) { requestContext.appendQueryParam("fieldIds", serializedParam); } @@ -75,7 +120,7 @@ export class PersonsApiRequestFactory extends BaseAPIRequestFactory { // Query Params if (fieldTypes !== undefined) { - const serializedParams = ObjectSerializer.serialize(fieldTypes, "Array<'enriched' | 'global' | 'relationship-intelligence'>", "string"); + const serializedParams = ObjectSerializer.serialize(fieldTypes, "Array<'enriched' | 'global' | 'relationship-intelligence'>", ""); for (const serializedParam of serializedParams) { requestContext.appendQueryParam("fieldTypes", serializedParam); } @@ -98,31 +143,45 @@ export class PersonsApiRequestFactory extends BaseAPIRequestFactory { } /** - * Returns metadata on non-list-specific Person Fields. Use the returned Field IDs to request field data from the GET `/v2/persons` and GET `/v2/persons/{id}` endpoints. - * Get metadata on Person Fields - * @param cursor Cursor for the next or previous page - * @param limit Number of items to include in the page + * Returns basic information and non-list-specific field data on the requested Person. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/persons/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Persons will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All People directory\" [permission](#section/Getting-Started/Permissions). + * Get a single Person + * @param personId Person ID + * @param fieldIds Field IDs for which to return field data + * @param fieldTypes Field Types for which to return field data */ - public async getV2PersonsFields(cursor?: string, limit?: number, _options?: Configuration): Promise { + public async v2PersonsPersonIdGET(personId: number, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: Configuration): Promise { let _config = _options || this.configuration; + // verify required parameter 'personId' is not null or undefined + if (personId === null || personId === undefined) { + throw new RequiredError("PersonsApi", "v2PersonsPersonIdGET", "personId"); + } + + // Path Params - const localVarPath = '/v2/persons/fields'; + const localVarPath = '/v2/persons/{personId}' + .replace('{' + 'personId' + '}', encodeURIComponent(String(personId))); // Make Request Context const requestContext = _config.baseServer.makeRequestContext(localVarPath, HttpMethod.GET); requestContext.setHeaderParam("Accept", "application/json, */*;q=0.8") // Query Params - if (cursor !== undefined) { - requestContext.setQueryParam("cursor", ObjectSerializer.serialize(cursor, "string", "")); + if (fieldIds !== undefined) { + const serializedParams = ObjectSerializer.serialize(fieldIds, "Array", ""); + for (const serializedParam of serializedParams) { + requestContext.appendQueryParam("fieldIds", serializedParam); + } } // Query Params - if (limit !== undefined) { - requestContext.setQueryParam("limit", ObjectSerializer.serialize(limit, "number", "int32")); + if (fieldTypes !== undefined) { + const serializedParams = ObjectSerializer.serialize(fieldTypes, "Array<'enriched' | 'global' | 'relationship-intelligence'>", ""); + for (const serializedParam of serializedParams) { + requestContext.appendQueryParam("fieldTypes", serializedParam); + } } @@ -142,45 +201,39 @@ export class PersonsApiRequestFactory extends BaseAPIRequestFactory { } /** - * Returns basic information and non-list-specific field data on the requested Person. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/persons/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Persons will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All People directory\" [permission](#section/Getting-Started/Permissions). - * Get a single Person - * @param id Person ID - * @param fieldIds Field IDs for which to return field data - * @param fieldTypes Field Types for which to return field data + * Paginate through the List Entries (AKA rows) for the given Person across all Lists. Each List Entry includes field data for the Person, including list-specific field data. Each List Entry also includes metadata about its creation, i.e., when it was added to the List and by whom. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Get a Person\'s List Entries + * @param personId Persons ID + * @param cursor Cursor for the next or previous page + * @param limit Number of items to include in the page */ - public async getV2PersonsId(id: number, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: Configuration): Promise { + public async v2PersonsPersonIdListEntriesGET(personId: number, cursor?: string, limit?: number, _options?: Configuration): Promise { let _config = _options || this.configuration; - // verify required parameter 'id' is not null or undefined - if (id === null || id === undefined) { - throw new RequiredError("PersonsApi", "getV2PersonsId", "id"); + // verify required parameter 'personId' is not null or undefined + if (personId === null || personId === undefined) { + throw new RequiredError("PersonsApi", "v2PersonsPersonIdListEntriesGET", "personId"); } // Path Params - const localVarPath = '/v2/persons/{id}' - .replace('{' + 'id' + '}', encodeURIComponent(String(id))); + const localVarPath = '/v2/persons/{personId}/list-entries' + .replace('{' + 'personId' + '}', encodeURIComponent(String(personId))); // Make Request Context const requestContext = _config.baseServer.makeRequestContext(localVarPath, HttpMethod.GET); requestContext.setHeaderParam("Accept", "application/json, */*;q=0.8") // Query Params - if (fieldIds !== undefined) { - const serializedParams = ObjectSerializer.serialize(fieldIds, "Array", "string"); - for (const serializedParam of serializedParams) { - requestContext.appendQueryParam("fieldIds", serializedParam); - } + if (cursor !== undefined) { + requestContext.setQueryParam("cursor", ObjectSerializer.serialize(cursor, "string", "")); } // Query Params - if (fieldTypes !== undefined) { - const serializedParams = ObjectSerializer.serialize(fieldTypes, "Array<'enriched' | 'global' | 'relationship-intelligence'>", "string"); - for (const serializedParam of serializedParams) { - requestContext.appendQueryParam("fieldTypes", serializedParam); - } + if (limit !== undefined) { + requestContext.setQueryParam("limit", ObjectSerializer.serialize(limit, "number", "int32")); } @@ -200,26 +253,26 @@ export class PersonsApiRequestFactory extends BaseAPIRequestFactory { } /** - * Paginate through the List Entries (AKA rows) for the given Person across all Lists. Each List Entry includes field data for the Person, including list-specific field data. Each List Entry also includes metadata about its creation, i.e., when it was added to the List and by whom. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Get a Person\'s List Entries - * @param id Persons ID + * Paginate through all Lists where the given Person appears as an entry and that you have access to view. Returns basic List information for each List that contains this Person. + * Get a Person\'s Lists + * @param personId Persons ID * @param cursor Cursor for the next or previous page * @param limit Number of items to include in the page */ - public async getV2PersonsIdListEntries(id: number, cursor?: string, limit?: number, _options?: Configuration): Promise { + public async v2PersonsPersonIdListsGET(personId: number, cursor?: string, limit?: number, _options?: Configuration): Promise { let _config = _options || this.configuration; - // verify required parameter 'id' is not null or undefined - if (id === null || id === undefined) { - throw new RequiredError("PersonsApi", "getV2PersonsIdListEntries", "id"); + // verify required parameter 'personId' is not null or undefined + if (personId === null || personId === undefined) { + throw new RequiredError("PersonsApi", "v2PersonsPersonIdListsGET", "personId"); } // Path Params - const localVarPath = '/v2/persons/{id}/list-entries' - .replace('{' + 'id' + '}', encodeURIComponent(String(id))); + const localVarPath = '/v2/persons/{personId}/lists' + .replace('{' + 'personId' + '}', encodeURIComponent(String(personId))); // Make Request Context const requestContext = _config.baseServer.makeRequestContext(localVarPath, HttpMethod.GET); @@ -252,31 +305,40 @@ export class PersonsApiRequestFactory extends BaseAPIRequestFactory { } /** - * Returns metadata for all the Lists on which the given Person appears. - * Get a Person\'s Lists - * @param id Persons ID + * | ⚠️ This endpoint is currently in BETA | |--| Returns notes for a given person id which includes directly attached notes, notes on meetings this person attended, and notes where this person is mentioned. You can filter notes using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|---------------------------------| | `creator.id` | Filter notes by the creator of the note | `int32` | `=` | `creator.id=1` | | `createdAt` | Filter notes by when it was created | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-02-04T10:48:24Z` | | `updatedAt` | Filter notes by when it was updated | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-02-03T10:48:24Z`| + * Get Notes for a Person + * @param personId Persons ID + * @param filter Filter options * @param cursor Cursor for the next or previous page * @param limit Number of items to include in the page + * @param totalCount Include total count of the collection in the pagination response */ - public async getV2PersonsIdLists(id: number, cursor?: string, limit?: number, _options?: Configuration): Promise { + public async v2PersonsPersonIdNotesGET(personId: number, filter?: string, cursor?: string, limit?: number, totalCount?: boolean, _options?: Configuration): Promise { let _config = _options || this.configuration; - // verify required parameter 'id' is not null or undefined - if (id === null || id === undefined) { - throw new RequiredError("PersonsApi", "getV2PersonsIdLists", "id"); + // verify required parameter 'personId' is not null or undefined + if (personId === null || personId === undefined) { + throw new RequiredError("PersonsApi", "v2PersonsPersonIdNotesGET", "personId"); } + + // Path Params - const localVarPath = '/v2/persons/{id}/lists' - .replace('{' + 'id' + '}', encodeURIComponent(String(id))); + const localVarPath = '/v2/persons/{personId}/notes' + .replace('{' + 'personId' + '}', encodeURIComponent(String(personId))); // Make Request Context const requestContext = _config.baseServer.makeRequestContext(localVarPath, HttpMethod.GET); requestContext.setHeaderParam("Accept", "application/json, */*;q=0.8") + // Query Params + if (filter !== undefined) { + requestContext.setQueryParam("filter", ObjectSerializer.serialize(filter, "string", "")); + } + // Query Params if (cursor !== undefined) { requestContext.setQueryParam("cursor", ObjectSerializer.serialize(cursor, "string", "")); @@ -287,6 +349,11 @@ export class PersonsApiRequestFactory extends BaseAPIRequestFactory { requestContext.setQueryParam("limit", ObjectSerializer.serialize(limit, "number", "int32")); } + // Query Params + if (totalCount !== undefined) { + requestContext.setQueryParam("totalCount", ObjectSerializer.serialize(totalCount, "boolean", "")); + } + let authMethod: SecurityAuthentication | undefined; // Apply auth methods @@ -311,31 +378,24 @@ export class PersonsApiResponseProcessor { * Unwraps the actual response sent by the server from the response context and deserializes the response content * to the expected objects * - * @params response Response returned by the server for a request to getV2Persons + * @params response Response returned by the server for a request to v2PersonsFieldsGET * @throws ApiException if the response code was not in [200, 299] */ - public async getV2PersonsWithHttpInfo(response: ResponseContext): Promise> { + public async v2PersonsFieldsGETWithHttpInfo(response: ResponseContext): Promise> { const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); if (isCodeInRange("200", response.httpStatusCode)) { - const body: PersonPaged = ObjectSerializer.deserialize( + const body: FieldMetadataPaged = ObjectSerializer.deserialize( ObjectSerializer.parse(await response.body.text(), contentType), - "PersonPaged", "" - ) as PersonPaged; + "FieldMetadataPaged", "" + ) as FieldMetadataPaged; return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); } if (isCodeInRange("400", response.httpStatusCode)) { - const body: InlineObject = ObjectSerializer.deserialize( + const body: Responses400 = ObjectSerializer.deserialize( ObjectSerializer.parse(await response.body.text(), contentType), - "InlineObject", "" - ) as InlineObject; - throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); - } - if (isCodeInRange("403", response.httpStatusCode)) { - const body: AuthorizationErrors = ObjectSerializer.deserialize( - ObjectSerializer.parse(await response.body.text(), contentType), - "AuthorizationErrors", "" - ) as AuthorizationErrors; - throw new ApiException(response.httpStatusCode, "Forbidden", body, response.headers); + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); } if (isCodeInRange("0", response.httpStatusCode)) { const body: Errors = ObjectSerializer.deserialize( @@ -347,10 +407,10 @@ export class PersonsApiResponseProcessor { // Work around for missing responses in specification, e.g. for petstore.yaml if (response.httpStatusCode >= 200 && response.httpStatusCode <= 299) { - const body: PersonPaged = ObjectSerializer.deserialize( + const body: FieldMetadataPaged = ObjectSerializer.deserialize( ObjectSerializer.parse(await response.body.text(), contentType), - "PersonPaged", "" - ) as PersonPaged; + "FieldMetadataPaged", "" + ) as FieldMetadataPaged; return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); } @@ -361,24 +421,31 @@ export class PersonsApiResponseProcessor { * Unwraps the actual response sent by the server from the response context and deserializes the response content * to the expected objects * - * @params response Response returned by the server for a request to getV2PersonsFields + * @params response Response returned by the server for a request to v2PersonsGET * @throws ApiException if the response code was not in [200, 299] */ - public async getV2PersonsFieldsWithHttpInfo(response: ResponseContext): Promise> { + public async v2PersonsGETWithHttpInfo(response: ResponseContext): Promise> { const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); if (isCodeInRange("200", response.httpStatusCode)) { - const body: FieldMetadataPaged = ObjectSerializer.deserialize( + const body: PersonPaged = ObjectSerializer.deserialize( ObjectSerializer.parse(await response.body.text(), contentType), - "FieldMetadataPaged", "" - ) as FieldMetadataPaged; + "PersonPaged", "" + ) as PersonPaged; return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); } if (isCodeInRange("400", response.httpStatusCode)) { - const body: InlineObject = ObjectSerializer.deserialize( + const body: Responses400 = ObjectSerializer.deserialize( ObjectSerializer.parse(await response.body.text(), contentType), - "InlineObject", "" - ) as InlineObject; - throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + } + if (isCodeInRange("403", response.httpStatusCode)) { + const body: AuthorizationErrors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "AuthorizationErrors", "" + ) as AuthorizationErrors; + throw new ApiException(response.httpStatusCode, "Forbidden", body, response.headers); } if (isCodeInRange("0", response.httpStatusCode)) { const body: Errors = ObjectSerializer.deserialize( @@ -390,10 +457,10 @@ export class PersonsApiResponseProcessor { // Work around for missing responses in specification, e.g. for petstore.yaml if (response.httpStatusCode >= 200 && response.httpStatusCode <= 299) { - const body: FieldMetadataPaged = ObjectSerializer.deserialize( + const body: PersonPaged = ObjectSerializer.deserialize( ObjectSerializer.parse(await response.body.text(), contentType), - "FieldMetadataPaged", "" - ) as FieldMetadataPaged; + "PersonPaged", "" + ) as PersonPaged; return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); } @@ -404,10 +471,10 @@ export class PersonsApiResponseProcessor { * Unwraps the actual response sent by the server from the response context and deserializes the response content * to the expected objects * - * @params response Response returned by the server for a request to getV2PersonsId + * @params response Response returned by the server for a request to v2PersonsPersonIdGET * @throws ApiException if the response code was not in [200, 299] */ - public async getV2PersonsIdWithHttpInfo(response: ResponseContext): Promise> { + public async v2PersonsPersonIdGETWithHttpInfo(response: ResponseContext): Promise> { const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); if (isCodeInRange("200", response.httpStatusCode)) { const body: Person = ObjectSerializer.deserialize( @@ -417,11 +484,11 @@ export class PersonsApiResponseProcessor { return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); } if (isCodeInRange("400", response.httpStatusCode)) { - const body: InlineObject = ObjectSerializer.deserialize( + const body: Responses400 = ObjectSerializer.deserialize( ObjectSerializer.parse(await response.body.text(), contentType), - "InlineObject", "" - ) as InlineObject; - throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); } if (isCodeInRange("403", response.httpStatusCode)) { const body: AuthorizationErrors = ObjectSerializer.deserialize( @@ -461,10 +528,10 @@ export class PersonsApiResponseProcessor { * Unwraps the actual response sent by the server from the response context and deserializes the response content * to the expected objects * - * @params response Response returned by the server for a request to getV2PersonsIdListEntries + * @params response Response returned by the server for a request to v2PersonsPersonIdListEntriesGET * @throws ApiException if the response code was not in [200, 299] */ - public async getV2PersonsIdListEntriesWithHttpInfo(response: ResponseContext): Promise> { + public async v2PersonsPersonIdListEntriesGETWithHttpInfo(response: ResponseContext): Promise> { const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); if (isCodeInRange("200", response.httpStatusCode)) { const body: ListEntryPaged = ObjectSerializer.deserialize( @@ -474,11 +541,11 @@ export class PersonsApiResponseProcessor { return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); } if (isCodeInRange("400", response.httpStatusCode)) { - const body: InlineObject = ObjectSerializer.deserialize( + const body: Responses400 = ObjectSerializer.deserialize( ObjectSerializer.parse(await response.body.text(), contentType), - "InlineObject", "" - ) as InlineObject; - throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); } if (isCodeInRange("403", response.httpStatusCode)) { const body: AuthorizationErrors = ObjectSerializer.deserialize( @@ -518,10 +585,10 @@ export class PersonsApiResponseProcessor { * Unwraps the actual response sent by the server from the response context and deserializes the response content * to the expected objects * - * @params response Response returned by the server for a request to getV2PersonsIdLists + * @params response Response returned by the server for a request to v2PersonsPersonIdListsGET * @throws ApiException if the response code was not in [200, 299] */ - public async getV2PersonsIdListsWithHttpInfo(response: ResponseContext): Promise> { + public async v2PersonsPersonIdListsGETWithHttpInfo(response: ResponseContext): Promise> { const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); if (isCodeInRange("200", response.httpStatusCode)) { const body: ListPaged = ObjectSerializer.deserialize( @@ -531,11 +598,11 @@ export class PersonsApiResponseProcessor { return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); } if (isCodeInRange("400", response.httpStatusCode)) { - const body: InlineObject = ObjectSerializer.deserialize( + const body: Responses400 = ObjectSerializer.deserialize( ObjectSerializer.parse(await response.body.text(), contentType), - "InlineObject", "" - ) as InlineObject; - throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); } if (isCodeInRange("404", response.httpStatusCode)) { const body: NotFoundErrors = ObjectSerializer.deserialize( @@ -564,4 +631,54 @@ export class PersonsApiResponseProcessor { throw new ApiException(response.httpStatusCode, "Unknown API Status Code!", await response.getBodyAsAny(), response.headers); } + /** + * Unwraps the actual response sent by the server from the response context and deserializes the response content + * to the expected objects + * + * @params response Response returned by the server for a request to v2PersonsPersonIdNotesGET + * @throws ApiException if the response code was not in [200, 299] + */ + public async v2PersonsPersonIdNotesGETWithHttpInfo(response: ResponseContext): Promise> { + const contentType = ObjectSerializer.normalizeMediaType(response.headers["content-type"]); + if (isCodeInRange("200", response.httpStatusCode)) { + const body: NotesNotesPaged = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "NotesNotesPaged", "" + ) as NotesNotesPaged; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + if (isCodeInRange("400", response.httpStatusCode)) { + const body: Responses400 = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Responses400", "" + ) as Responses400; + throw new ApiException(response.httpStatusCode, "Bad Request", body, response.headers); + } + if (isCodeInRange("404", response.httpStatusCode)) { + const body: NotFoundErrors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "NotFoundErrors", "" + ) as NotFoundErrors; + throw new ApiException(response.httpStatusCode, "Not Found", body, response.headers); + } + if (isCodeInRange("0", response.httpStatusCode)) { + const body: Errors = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "Errors", "" + ) as Errors; + throw new ApiException(response.httpStatusCode, "Errors", body, response.headers); + } + + // Work around for missing responses in specification, e.g. for petstore.yaml + if (response.httpStatusCode >= 200 && response.httpStatusCode <= 299) { + const body: NotesNotesPaged = ObjectSerializer.deserialize( + ObjectSerializer.parse(await response.body.text(), contentType), + "NotesNotesPaged", "" + ) as NotesNotesPaged; + return new HttpInfo(response.httpStatusCode, response.headers, response.body, body); + } + + throw new ApiException(response.httpStatusCode, "Unknown API Status Code!", await response.getBodyAsAny(), response.headers); + } + } diff --git a/src/v2/generated/apis/exception.ts b/src/v2/generated/apis/exception.ts index 9365d33..00f294c 100644 --- a/src/v2/generated/apis/exception.ts +++ b/src/v2/generated/apis/exception.ts @@ -10,6 +10,6 @@ export class ApiException extends Error { public constructor(public code: number, message: string, public body: T, public headers: { [key: string]: string; }) { super("HTTP-Code: " + code + "\nMessage: " + message + "\nBody: " + JSON.stringify(body) + "\nHeaders: " + - JSON.stringify(headers)) + JSON.stringify(headers)); } -} +} \ No newline at end of file diff --git a/src/v2/generated/auth/auth.ts b/src/v2/generated/auth/auth.ts index 8e53bf2..80c8ec1 100644 --- a/src/v2/generated/auth/auth.ts +++ b/src/v2/generated/auth/auth.ts @@ -41,7 +41,6 @@ export class BearerAuthAuthentication implements SecurityAuthentication { } } - export type AuthMethods = { "default"?: SecurityAuthentication, "bearerAuth"?: SecurityAuthentication diff --git a/src/v2/generated/configuration.ts b/src/v2/generated/configuration.ts index c923809..2869965 100644 --- a/src/v2/generated/configuration.ts +++ b/src/v2/generated/configuration.ts @@ -5,16 +5,16 @@ import { BaseServerConfiguration, server1 } from "./servers.ts"; import { configureAuthMethods, AuthMethods, AuthMethodsConfiguration } from "./auth/auth.ts"; export interface Configuration { - readonly baseServer: BaseServerConfiguration; - readonly httpApi: HttpLibrary; - readonly middleware: M[]; - readonly authMethods: AuthMethods; + readonly baseServer: BaseServerConfiguration; + readonly httpApi: HttpLibrary; + readonly middleware: M[]; + readonly authMethods: AuthMethods; } // Additional option specific to middleware merge strategy export interface MiddlewareMergeOptions { - // default is `'replace'` for backwards compatibility - middlewareMergeStrategy?: 'replace' | 'append' | 'prepend'; + // default is `"replace"` for backwards compatibility + middlewareMergeStrategy?: "replace" | "append" | "prepend"; } // Unify configuration options using Partial plus extra merge strategy @@ -29,36 +29,36 @@ export type PromiseConfigurationOptions = ConfigurationOptions new PromiseMiddlewareWrapper(m) + ), + middlewareMergeStrategy: options.middlewareMergeStrategy, + authMethods: options.authMethods, + }; + } + return; +} diff --git a/src/v2/generated/http/http.ts b/src/v2/generated/http/http.ts index 922bfd7..0b57a8a 100644 --- a/src/v2/generated/http/http.ts +++ b/src/v2/generated/http/http.ts @@ -48,6 +48,7 @@ export class RequestContext { private headers: Headers = {}; private body: RequestBody = undefined; private url: URL; + private signal: AbortSignal | undefined = undefined; /** * Creates the request context using a http method and request resource url @@ -124,6 +125,15 @@ export class RequestContext { public setHeaderParam(key: string, value: string): void { this.headers[key] = value; } + + public setSignal(signal: AbortSignal): void { + this.signal = signal; + } + + public getSignal(): AbortSignal | undefined { + return this.signal; + } + } export interface ResponseBody { diff --git a/src/v2/generated/http/isomorphic-fetch.ts b/src/v2/generated/http/isomorphic-fetch.ts index a752135..af9057a 100644 --- a/src/v2/generated/http/isomorphic-fetch.ts +++ b/src/v2/generated/http/isomorphic-fetch.ts @@ -11,6 +11,7 @@ export class IsomorphicFetchHttpLibrary implements HttpLibrary { method: method, body: body as any, headers: request.getHeaders(), + signal: request.getSignal(), }).then((resp: any) => { const headers: { [name: string]: string } = {}; resp.headers.forEach((value: string, name: string) => { diff --git a/src/v2/generated/index.ts b/src/v2/generated/index.ts index 2efb8d2..928e145 100644 --- a/src/v2/generated/index.ts +++ b/src/v2/generated/index.ts @@ -9,5 +9,5 @@ export { RequiredError } from "./apis/baseapi.ts"; export type { PromiseMiddleware as Middleware, Middleware as ObservableMiddleware } from './middleware.ts'; export { Observable } from './rxjsStub.ts'; -export { type AuthApiGetV2AuthWhoamiRequest, ObjectAuthApi as AuthApi, type CompaniesApiGetV2CompaniesRequest, type CompaniesApiGetV2CompaniesFieldsRequest, type CompaniesApiGetV2CompaniesIdRequest, type CompaniesApiGetV2CompaniesIdListEntriesRequest, type CompaniesApiGetV2CompaniesIdListsRequest, ObjectCompaniesApi as CompaniesApi, type ListsApiGetV2ListsListidSavedViewsRequest, type ListsApiGetV2ListsListidSavedViewsViewidRequest, type ListsApiGetV2ListsListidSavedViewsViewidListEntriesRequest, type ListsApiV2ListsGETRequest, type ListsApiV2ListsListIdFieldsGETRequest, type ListsApiV2ListsListIdGETRequest, type ListsApiV2ListsListIdListEntriesGETRequest, type ListsApiV2ListsListIdListEntriesListEntryIdFieldsFieldIdGETRequest, type ListsApiV2ListsListIdListEntriesListEntryIdFieldsFieldIdPOSTRequest, type ListsApiV2ListsListIdListEntriesListEntryIdFieldsGETRequest, type ListsApiV2ListsListIdListEntriesListEntryIdFieldsPATCHRequest, type ListsApiV2ListsListIdListEntriesListEntryIdGETRequest, ObjectListsApi as ListsApi, type OpportunitiesApiGetV2OpportunitiesRequest, type OpportunitiesApiGetV2OpportunitiesIdRequest, ObjectOpportunitiesApi as OpportunitiesApi, type PersonsApiGetV2PersonsRequest, type PersonsApiGetV2PersonsFieldsRequest, type PersonsApiGetV2PersonsIdRequest, type PersonsApiGetV2PersonsIdListEntriesRequest, type PersonsApiGetV2PersonsIdListsRequest, ObjectPersonsApi as PersonsApi } from './types/ObjectParamAPI.ts'; +export { type AuthApiV2AuthWhoamiGETRequest, ObjectAuthApi as AuthApi, type CallsApiV2CallsGETRequest, ObjectCallsApi as CallsApi, type ChatMessagesApiV2ChatMessagesGETRequest, ObjectChatMessagesApi as ChatMessagesApi, type CompaniesApiV2CompaniesCompanyIdGETRequest, type CompaniesApiV2CompaniesCompanyIdListEntriesGETRequest, type CompaniesApiV2CompaniesCompanyIdListsGETRequest, type CompaniesApiV2CompaniesCompanyIdNotesGETRequest, type CompaniesApiV2CompaniesFieldsGETRequest, type CompaniesApiV2CompaniesGETRequest, ObjectCompaniesApi as CompaniesApi, type CompanyMergesApiV2CompanyMergesGETRequest, type CompanyMergesApiV2CompanyMergesMergeIdGETRequest, type CompanyMergesApiV2CompanyMergesPOSTRequest, type CompanyMergesApiV2TasksCompanyMergesGETRequest, type CompanyMergesApiV2TasksCompanyMergesTaskIdGETRequest, ObjectCompanyMergesApi as CompanyMergesApi, type EmailsApiV2EmailsGETRequest, ObjectEmailsApi as EmailsApi, type ListsApiV2ListsGETRequest, type ListsApiV2ListsListIdFieldsGETRequest, type ListsApiV2ListsListIdGETRequest, type ListsApiV2ListsListIdListEntriesGETRequest, type ListsApiV2ListsListIdListEntriesListEntryIdFieldsFieldIdGETRequest, type ListsApiV2ListsListIdListEntriesListEntryIdFieldsFieldIdPOSTRequest, type ListsApiV2ListsListIdListEntriesListEntryIdFieldsGETRequest, type ListsApiV2ListsListIdListEntriesListEntryIdFieldsPATCHRequest, type ListsApiV2ListsListIdListEntriesListEntryIdGETRequest, type ListsApiV2ListsListIdSavedViewsGETRequest, type ListsApiV2ListsListIdSavedViewsViewIdGETRequest, type ListsApiV2ListsListIdSavedViewsViewIdListEntriesGETRequest, ObjectListsApi as ListsApi, type MeetingsApiV2MeetingsGETRequest, ObjectMeetingsApi as MeetingsApi, type NotesApiV2NotesGETRequest, type NotesApiV2NotesNoteIdAttachedCompaniesGETRequest, type NotesApiV2NotesNoteIdAttachedOpportunitiesGETRequest, type NotesApiV2NotesNoteIdAttachedPersonsGETRequest, type NotesApiV2NotesNoteIdGETRequest, type NotesApiV2NotesNoteIdRepliesGETRequest, ObjectNotesApi as NotesApi, type OpportunitiesApiV2OpportunitiesGETRequest, type OpportunitiesApiV2OpportunitiesOpportunityIdGETRequest, type OpportunitiesApiV2OpportunitiesOpportunityIdNotesGETRequest, ObjectOpportunitiesApi as OpportunitiesApi, type PersonMergesApiV2PersonMergesGETRequest, type PersonMergesApiV2PersonMergesMergeIdGETRequest, type PersonMergesApiV2PersonMergesPOSTRequest, type PersonMergesApiV2TasksPersonMergesGETRequest, type PersonMergesApiV2TasksPersonMergesTaskIdGETRequest, ObjectPersonMergesApi as PersonMergesApi, type PersonsApiV2PersonsFieldsGETRequest, type PersonsApiV2PersonsGETRequest, type PersonsApiV2PersonsPersonIdGETRequest, type PersonsApiV2PersonsPersonIdListEntriesGETRequest, type PersonsApiV2PersonsPersonIdListsGETRequest, type PersonsApiV2PersonsPersonIdNotesGETRequest, ObjectPersonsApi as PersonsApi } from './types/ObjectParamAPI.ts'; diff --git a/src/v2/generated/middleware.ts b/src/v2/generated/middleware.ts index ae36e6c..530fade 100644 --- a/src/v2/generated/middleware.ts +++ b/src/v2/generated/middleware.ts @@ -26,10 +26,7 @@ export interface Middleware { } export class PromiseMiddlewareWrapper implements Middleware { - - public constructor(private middleware: PromiseMiddleware) { - - } + public constructor(private middleware: PromiseMiddleware) {} pre(context: RequestContext): Observable { return from(this.middleware.pre(context)); @@ -38,7 +35,6 @@ export class PromiseMiddlewareWrapper implements Middleware { post(context: ResponseContext): Observable { return from(this.middleware.post(context)); } - } /** diff --git a/src/v2/generated/models/Attendee.ts b/src/v2/generated/models/Attendee.ts index 03cff92..00bd981 100644 --- a/src/v2/generated/models/Attendee.ts +++ b/src/v2/generated/models/Attendee.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/AttendeesPreview.ts b/src/v2/generated/models/AttendeesPreview.ts new file mode 100644 index 0000000..75ac415 --- /dev/null +++ b/src/v2/generated/models/AttendeesPreview.ts @@ -0,0 +1,50 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { Attendee } from '../models/Attendee.ts'; +import { HttpFile } from '../http/http.ts'; + +export class AttendeesPreview { + /** + * A preview of Attendees + */ + 'data': Array; + /** + * The total count of Attendees + */ + 'totalCount': number; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "data", + "baseName": "data", + "type": "Array", + "format": "" + }, + { + "name": "totalCount", + "baseName": "totalCount", + "type": "number", + "format": "int64" + } ]; + + static getAttributeTypeMap() { + return AttendeesPreview.attributeTypeMap; + } + + public constructor() { + } +} diff --git a/src/v2/generated/models/AuthenticationError.ts b/src/v2/generated/models/AuthenticationError.ts index 02afc79..3a676e4 100644 --- a/src/v2/generated/models/AuthenticationError.ts +++ b/src/v2/generated/models/AuthenticationError.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/AuthorizationError.ts b/src/v2/generated/models/AuthorizationError.ts index be52a28..28cb216 100644 --- a/src/v2/generated/models/AuthorizationError.ts +++ b/src/v2/generated/models/AuthorizationError.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/AuthorizationErrors.ts b/src/v2/generated/models/AuthorizationErrors.ts index e9f80dc..b3525c5 100644 --- a/src/v2/generated/models/AuthorizationErrors.ts +++ b/src/v2/generated/models/AuthorizationErrors.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/BadRequestError.ts b/src/v2/generated/models/BadRequestError.ts index a07c7c6..da4c730 100644 --- a/src/v2/generated/models/BadRequestError.ts +++ b/src/v2/generated/models/BadRequestError.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/ChatMessage.ts b/src/v2/generated/models/ChatMessage.ts index 7b8a140..021609d 100644 --- a/src/v2/generated/models/ChatMessage.ts +++ b/src/v2/generated/models/ChatMessage.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/CompaniesValue.ts b/src/v2/generated/models/CompaniesValue.ts index d8cc2af..2757726 100644 --- a/src/v2/generated/models/CompaniesValue.ts +++ b/src/v2/generated/models/CompaniesValue.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/CompaniesValueUpdate.ts b/src/v2/generated/models/CompaniesValueUpdate.ts index dbe6f0f..b206545 100644 --- a/src/v2/generated/models/CompaniesValueUpdate.ts +++ b/src/v2/generated/models/CompaniesValueUpdate.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/Company.ts b/src/v2/generated/models/Company.ts index 51ba589..2d827bb 100644 --- a/src/v2/generated/models/Company.ts +++ b/src/v2/generated/models/Company.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -28,7 +28,7 @@ export class Company { /** * The company\'s primary domain */ - 'domain': string; + 'domain': string | null; /** * All of the company\'s domains */ diff --git a/src/v2/generated/models/CompanyData.ts b/src/v2/generated/models/CompanyData.ts index b891dba..4c83472 100644 --- a/src/v2/generated/models/CompanyData.ts +++ b/src/v2/generated/models/CompanyData.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/CompanyDataPaged.ts b/src/v2/generated/models/CompanyDataPaged.ts new file mode 100644 index 0000000..7e5dfa3 --- /dev/null +++ b/src/v2/generated/models/CompanyDataPaged.ts @@ -0,0 +1,51 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { CompanyData } from '../models/CompanyData.ts'; +import { Pagination } from '../models/Pagination.ts'; +import { HttpFile } from '../http/http.ts'; + +/** +* CompanyDataPaged model +*/ +export class CompanyDataPaged { + /** + * A page of Company results + */ + 'data': Array; + 'pagination': Pagination; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "data", + "baseName": "data", + "type": "Array", + "format": "" + }, + { + "name": "pagination", + "baseName": "pagination", + "type": "Pagination", + "format": "" + } ]; + + static getAttributeTypeMap() { + return CompanyDataPaged.attributeTypeMap; + } + + public constructor() { + } +} diff --git a/src/v2/generated/models/CompanyListEntry.ts b/src/v2/generated/models/CompanyListEntry.ts index 066d72b..741c196 100644 --- a/src/v2/generated/models/CompanyListEntry.ts +++ b/src/v2/generated/models/CompanyListEntry.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/CompanyMergeRequest.ts b/src/v2/generated/models/CompanyMergeRequest.ts new file mode 100644 index 0000000..b33a4be --- /dev/null +++ b/src/v2/generated/models/CompanyMergeRequest.ts @@ -0,0 +1,52 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { HttpFile } from '../http/http.ts'; + +/** +* Request body for initiating a company merge +*/ +export class CompanyMergeRequest { + /** + * The ID of the company profile that will be kept after the merge. All data from the duplicate company will be merged into this company. + */ + 'primaryCompanyId': number; + /** + * The ID of the company profile that will be merged and then deleted. All data from this company will be transferred to the primary company. + */ + 'duplicateCompanyId': number; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "primaryCompanyId", + "baseName": "primaryCompanyId", + "type": "number", + "format": "int64" + }, + { + "name": "duplicateCompanyId", + "baseName": "duplicateCompanyId", + "type": "number", + "format": "int64" + } ]; + + static getAttributeTypeMap() { + return CompanyMergeRequest.attributeTypeMap; + } + + public constructor() { + } +} diff --git a/src/v2/generated/models/CompanyMergeResponse.ts b/src/v2/generated/models/CompanyMergeResponse.ts new file mode 100644 index 0000000..ed07c30 --- /dev/null +++ b/src/v2/generated/models/CompanyMergeResponse.ts @@ -0,0 +1,42 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { HttpFile } from '../http/http.ts'; + +/** +* Response body for initiating a company merge +*/ +export class CompanyMergeResponse { + /** + * URL to check the status of the merge task + */ + 'taskUrl': string; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "taskUrl", + "baseName": "taskUrl", + "type": "string", + "format": "uri" + } ]; + + static getAttributeTypeMap() { + return CompanyMergeResponse.attributeTypeMap; + } + + public constructor() { + } +} diff --git a/src/v2/generated/models/CompanyMergeState.ts b/src/v2/generated/models/CompanyMergeState.ts new file mode 100644 index 0000000..ec6abfd --- /dev/null +++ b/src/v2/generated/models/CompanyMergeState.ts @@ -0,0 +1,119 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { HttpFile } from '../http/http.ts'; + +/** +* Entity representing the state of an individual company merge +*/ +export class CompanyMergeState { + /** + * The unique identifier for the merge + */ + 'id': number; + /** + * Current status of the merge + */ + 'status': CompanyMergeStateStatusEnum; + /** + * Identifier for the task this merge belongs to + */ + 'taskId': string; + /** + * Timestamp when the merge started + */ + 'startedAt': Date; + /** + * ID of the primary company that other profiles were merged into + */ + 'primaryCompanyId': number; + /** + * ID of the duplicate company that was merged into the primary company + */ + 'duplicateCompanyId': number; + /** + * Timestamp when the merge completed (success or failure) + */ + 'completedAt': Date | null; + /** + * Error message if the merge failed + */ + 'errorMessage': string | null; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "id", + "baseName": "id", + "type": "number", + "format": "int64" + }, + { + "name": "status", + "baseName": "status", + "type": "CompanyMergeStateStatusEnum", + "format": "" + }, + { + "name": "taskId", + "baseName": "taskId", + "type": "string", + "format": "uuid" + }, + { + "name": "startedAt", + "baseName": "startedAt", + "type": "Date", + "format": "date-time" + }, + { + "name": "primaryCompanyId", + "baseName": "primaryCompanyId", + "type": "number", + "format": "int64" + }, + { + "name": "duplicateCompanyId", + "baseName": "duplicateCompanyId", + "type": "number", + "format": "int64" + }, + { + "name": "completedAt", + "baseName": "completedAt", + "type": "Date", + "format": "date-time" + }, + { + "name": "errorMessage", + "baseName": "errorMessage", + "type": "string", + "format": "" + } ]; + + static getAttributeTypeMap() { + return CompanyMergeState.attributeTypeMap; + } + + public constructor() { + } +} + +export enum CompanyMergeStateStatusEnum { + InProgress = 'in-progress', + Success = 'success', + Failed = 'failed' +} + diff --git a/src/v2/generated/models/CompanyMergeStatePaged.ts b/src/v2/generated/models/CompanyMergeStatePaged.ts new file mode 100644 index 0000000..d6012ca --- /dev/null +++ b/src/v2/generated/models/CompanyMergeStatePaged.ts @@ -0,0 +1,51 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { CompanyMergeState } from '../models/CompanyMergeState.ts'; +import { Pagination } from '../models/Pagination.ts'; +import { HttpFile } from '../http/http.ts'; + +/** +* Paginated list of company merge states +*/ +export class CompanyMergeStatePaged { + /** + * Array of company merge states + */ + 'data': Array; + 'pagination': Pagination; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "data", + "baseName": "data", + "type": "Array", + "format": "" + }, + { + "name": "pagination", + "baseName": "pagination", + "type": "Pagination", + "format": "" + } ]; + + static getAttributeTypeMap() { + return CompanyMergeStatePaged.attributeTypeMap; + } + + public constructor() { + } +} diff --git a/src/v2/generated/models/CompanyMergeTask.ts b/src/v2/generated/models/CompanyMergeTask.ts new file mode 100644 index 0000000..ca90140 --- /dev/null +++ b/src/v2/generated/models/CompanyMergeTask.ts @@ -0,0 +1,67 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { CompanyMergeTaskResultsSummary } from '../models/CompanyMergeTaskResultsSummary.ts'; +import { HttpFile } from '../http/http.ts'; + +/** +* Company merge task details and status for batch operations +*/ +export class CompanyMergeTask { + /** + * The unique identifier for this merge task + */ + 'id': string; + /** + * The current status of the batch operation + */ + 'status': CompanyMergeTaskStatusEnum; + 'resultsSummary': CompanyMergeTaskResultsSummary; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "id", + "baseName": "id", + "type": "string", + "format": "uuid" + }, + { + "name": "status", + "baseName": "status", + "type": "CompanyMergeTaskStatusEnum", + "format": "" + }, + { + "name": "resultsSummary", + "baseName": "resultsSummary", + "type": "CompanyMergeTaskResultsSummary", + "format": "" + } ]; + + static getAttributeTypeMap() { + return CompanyMergeTask.attributeTypeMap; + } + + public constructor() { + } +} + +export enum CompanyMergeTaskStatusEnum { + InProgress = 'in-progress', + Success = 'success', + Failed = 'failed' +} + diff --git a/src/v2/generated/models/CompanyMergeTaskPaged.ts b/src/v2/generated/models/CompanyMergeTaskPaged.ts new file mode 100644 index 0000000..ef6b54a --- /dev/null +++ b/src/v2/generated/models/CompanyMergeTaskPaged.ts @@ -0,0 +1,51 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { CompanyMergeTask } from '../models/CompanyMergeTask.ts'; +import { Pagination } from '../models/Pagination.ts'; +import { HttpFile } from '../http/http.ts'; + +/** +* Paginated list of company merge tasks +*/ +export class CompanyMergeTaskPaged { + /** + * Array of company merge tasks + */ + 'data': Array; + 'pagination': Pagination; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "data", + "baseName": "data", + "type": "Array", + "format": "" + }, + { + "name": "pagination", + "baseName": "pagination", + "type": "Pagination", + "format": "" + } ]; + + static getAttributeTypeMap() { + return CompanyMergeTaskPaged.attributeTypeMap; + } + + public constructor() { + } +} diff --git a/src/v2/generated/models/CompanyMergeTaskResultsSummary.ts b/src/v2/generated/models/CompanyMergeTaskResultsSummary.ts new file mode 100644 index 0000000..d662854 --- /dev/null +++ b/src/v2/generated/models/CompanyMergeTaskResultsSummary.ts @@ -0,0 +1,72 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { HttpFile } from '../http/http.ts'; + +/** +* Summary of merges in this batch task +*/ +export class CompanyMergeTaskResultsSummary { + /** + * Total number of merges in the batch + */ + 'total': number; + /** + * Number of merges currently in progress + */ + 'inProgress': number; + /** + * Number of successfully completed merges + */ + 'success': number; + /** + * Number of failed merges + */ + 'failed': number; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "total", + "baseName": "total", + "type": "number", + "format": "int32" + }, + { + "name": "inProgress", + "baseName": "inProgress", + "type": "number", + "format": "int32" + }, + { + "name": "success", + "baseName": "success", + "type": "number", + "format": "int32" + }, + { + "name": "failed", + "baseName": "failed", + "type": "number", + "format": "int32" + } ]; + + static getAttributeTypeMap() { + return CompanyMergeTaskResultsSummary.attributeTypeMap; + } + + public constructor() { + } +} diff --git a/src/v2/generated/models/CompanyPaged.ts b/src/v2/generated/models/CompanyPaged.ts index 748aad7..0551ba1 100644 --- a/src/v2/generated/models/CompanyPaged.ts +++ b/src/v2/generated/models/CompanyPaged.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/CompanyReference.ts b/src/v2/generated/models/CompanyReference.ts index 34aaaf5..d209c1f 100644 --- a/src/v2/generated/models/CompanyReference.ts +++ b/src/v2/generated/models/CompanyReference.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/CompanyValue.ts b/src/v2/generated/models/CompanyValue.ts index 5069aec..c751bf2 100644 --- a/src/v2/generated/models/CompanyValue.ts +++ b/src/v2/generated/models/CompanyValue.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/CompanyValueUpdate.ts b/src/v2/generated/models/CompanyValueUpdate.ts index fa71149..7f8d488 100644 --- a/src/v2/generated/models/CompanyValueUpdate.ts +++ b/src/v2/generated/models/CompanyValueUpdate.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/ConflictError.ts b/src/v2/generated/models/ConflictError.ts index 0af53da..9204703 100644 --- a/src/v2/generated/models/ConflictError.ts +++ b/src/v2/generated/models/ConflictError.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/DateValue.ts b/src/v2/generated/models/DateValue.ts index 3bb30b2..cff5aab 100644 --- a/src/v2/generated/models/DateValue.ts +++ b/src/v2/generated/models/DateValue.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/Dropdown.ts b/src/v2/generated/models/Dropdown.ts index 4cc23c5..0f7fb32 100644 --- a/src/v2/generated/models/Dropdown.ts +++ b/src/v2/generated/models/Dropdown.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/DropdownReference.ts b/src/v2/generated/models/DropdownReference.ts index a5e0a5f..f6ff6a9 100644 --- a/src/v2/generated/models/DropdownReference.ts +++ b/src/v2/generated/models/DropdownReference.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/DropdownValue.ts b/src/v2/generated/models/DropdownValue.ts index add3dc0..b6d7b59 100644 --- a/src/v2/generated/models/DropdownValue.ts +++ b/src/v2/generated/models/DropdownValue.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/DropdownValueUpdate.ts b/src/v2/generated/models/DropdownValueUpdate.ts index a75b3c1..116a7e8 100644 --- a/src/v2/generated/models/DropdownValueUpdate.ts +++ b/src/v2/generated/models/DropdownValueUpdate.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/DropdownsValue.ts b/src/v2/generated/models/DropdownsValue.ts index 9cb0910..91999dd 100644 --- a/src/v2/generated/models/DropdownsValue.ts +++ b/src/v2/generated/models/DropdownsValue.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/DropdownsValueUpdate.ts b/src/v2/generated/models/DropdownsValueUpdate.ts index e29a766..886ab63 100644 --- a/src/v2/generated/models/DropdownsValueUpdate.ts +++ b/src/v2/generated/models/DropdownsValueUpdate.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/Email.ts b/src/v2/generated/models/Email.ts index 21effda..48d9a07 100644 --- a/src/v2/generated/models/Email.ts +++ b/src/v2/generated/models/Email.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/Errors.ts b/src/v2/generated/models/Errors.ts index 303e0d6..a3a65c2 100644 --- a/src/v2/generated/models/Errors.ts +++ b/src/v2/generated/models/Errors.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/Field.ts b/src/v2/generated/models/Field.ts index beda942..7238cc9 100644 --- a/src/v2/generated/models/Field.ts +++ b/src/v2/generated/models/Field.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -84,6 +84,8 @@ export enum FieldTypeEnum { } export enum FieldEnrichmentSourceEnum { AffinityData = 'affinity-data', - Dealroom = 'dealroom' + Dealroom = 'dealroom', + Eventbrite = 'eventbrite', + Mailchimp = 'mailchimp' } diff --git a/src/v2/generated/models/FieldMetadata.ts b/src/v2/generated/models/FieldMetadata.ts index 95287ed..d559133 100644 --- a/src/v2/generated/models/FieldMetadata.ts +++ b/src/v2/generated/models/FieldMetadata.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -86,7 +86,9 @@ export enum FieldMetadataTypeEnum { } export enum FieldMetadataEnrichmentSourceEnum { AffinityData = 'affinity-data', - Dealroom = 'dealroom' + Dealroom = 'dealroom', + Eventbrite = 'eventbrite', + Mailchimp = 'mailchimp' } export enum FieldMetadataValueTypeEnum { Person = 'person', diff --git a/src/v2/generated/models/FieldMetadataPaged.ts b/src/v2/generated/models/FieldMetadataPaged.ts index 8089cbf..6e87338 100644 --- a/src/v2/generated/models/FieldMetadataPaged.ts +++ b/src/v2/generated/models/FieldMetadataPaged.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/FieldPaged.ts b/src/v2/generated/models/FieldPaged.ts index f986f9c..83bc2c5 100644 --- a/src/v2/generated/models/FieldPaged.ts +++ b/src/v2/generated/models/FieldPaged.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/FieldUpdate.ts b/src/v2/generated/models/FieldUpdate.ts index 0f1731b..dac10e0 100644 --- a/src/v2/generated/models/FieldUpdate.ts +++ b/src/v2/generated/models/FieldUpdate.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/FieldValue.ts b/src/v2/generated/models/FieldValue.ts index 40a2687..03baba2 100644 --- a/src/v2/generated/models/FieldValue.ts +++ b/src/v2/generated/models/FieldValue.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/FieldValueUpdate.ts b/src/v2/generated/models/FieldValueUpdate.ts index a642c67..9633967 100644 --- a/src/v2/generated/models/FieldValueUpdate.ts +++ b/src/v2/generated/models/FieldValueUpdate.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/FloatValue.ts b/src/v2/generated/models/FloatValue.ts index e530846..cbc51ce 100644 --- a/src/v2/generated/models/FloatValue.ts +++ b/src/v2/generated/models/FloatValue.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/FloatsValue.ts b/src/v2/generated/models/FloatsValue.ts index aa3c730..69dd570 100644 --- a/src/v2/generated/models/FloatsValue.ts +++ b/src/v2/generated/models/FloatsValue.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/FormulaNumber.ts b/src/v2/generated/models/FormulaNumber.ts index c57d229..ba1343a 100644 --- a/src/v2/generated/models/FormulaNumber.ts +++ b/src/v2/generated/models/FormulaNumber.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/FormulaValue.ts b/src/v2/generated/models/FormulaValue.ts index d71a593..bc14d5f 100644 --- a/src/v2/generated/models/FormulaValue.ts +++ b/src/v2/generated/models/FormulaValue.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/Grant.ts b/src/v2/generated/models/Grant.ts index b17f576..82402a1 100644 --- a/src/v2/generated/models/Grant.ts +++ b/src/v2/generated/models/Grant.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -59,6 +59,7 @@ export class Grant { } export enum GrantTypeEnum { - ApiKey = 'api-key' + ApiKey = 'api-key', + AccessToken = 'access-token' } diff --git a/src/v2/generated/models/InlineObject.ts b/src/v2/generated/models/InlineObject.ts deleted file mode 100644 index a16f97b..0000000 --- a/src/v2/generated/models/InlineObject.ts +++ /dev/null @@ -1,37 +0,0 @@ -/** - * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. - * - * OpenAPI spec version: 2024-01-01 - * Contact: support@affinity.co - * - * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). - * https://openapi-generator.tech - * Do not edit the class manually. - */ - -import { InlineObjectErrorsInner } from '../models/InlineObjectErrorsInner.ts'; -import { HttpFile } from '../http/http.ts'; - -export class InlineObject { - 'errors': Array; - - static readonly discriminator: string | undefined = undefined; - - static readonly mapping: {[index: string]: string} | undefined = undefined; - - static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ - { - "name": "errors", - "baseName": "errors", - "type": "Array", - "format": "" - } ]; - - static getAttributeTypeMap() { - return InlineObject.attributeTypeMap; - } - - public constructor() { - } -} diff --git a/src/v2/generated/models/InlineObjectErrorsInner.ts b/src/v2/generated/models/InlineObjectErrorsInner.ts deleted file mode 100644 index 4f9b0b4..0000000 --- a/src/v2/generated/models/InlineObjectErrorsInner.ts +++ /dev/null @@ -1,36 +0,0 @@ -/** - * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. - * - * OpenAPI spec version: 2024-01-01 - * Contact: support@affinity.co - * - * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). - * https://openapi-generator.tech - * Do not edit the class manually. - */ - -import { BadRequestError } from '../models/BadRequestError.ts'; -import { ValidationError } from '../models/ValidationError.ts'; -import { HttpFile } from '../http/http.ts'; - -/** - * @type InlineObjectErrorsInner - * Type - * @export - */ -export type InlineObjectErrorsInner = BadRequestError | ValidationError; - -/** -* @type InlineObjectErrorsInnerClass -* @export -*/ -export class InlineObjectErrorsInnerClass { - static readonly discriminator: string | undefined = "code"; - - static readonly mapping: {[index: string]: string} | undefined = { - "bad-request": "BadRequestError", - "validation": "ValidationError", - }; -} - diff --git a/src/v2/generated/models/Interaction.ts b/src/v2/generated/models/Interaction.ts index 3416cce..527cc40 100644 --- a/src/v2/generated/models/Interaction.ts +++ b/src/v2/generated/models/Interaction.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/InteractionValue.ts b/src/v2/generated/models/InteractionValue.ts index 7104b9e..aa7b9c0 100644 --- a/src/v2/generated/models/InteractionValue.ts +++ b/src/v2/generated/models/InteractionValue.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/InteractionsCall.ts b/src/v2/generated/models/InteractionsCall.ts new file mode 100644 index 0000000..396999f --- /dev/null +++ b/src/v2/generated/models/InteractionsCall.ts @@ -0,0 +1,133 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { Attendee } from '../models/Attendee.ts'; +import { AttendeesPreview } from '../models/AttendeesPreview.ts'; +import { HttpFile } from '../http/http.ts'; + +export class InteractionsCall { + /** + * The call\'s unique identifier + */ + 'id': number; + /** + * Indicates how the interaction was added to Affinity: either manually by a user (\'manual\') or automatically through Affinity\'s capture process (\'automated\'). Currently, calls can only be logged as \'manual\'. + */ + 'loggingType': InteractionsCallLoggingTypeEnum; + /** + * The call\'s title + */ + 'title': string | null; + /** + * The timestamp of when the call starts + */ + 'startTime': Date; + /** + * The timestamp of when the call ends + */ + 'endTime': Date | null; + /** + * Whether the call is all day + */ + 'allDay': boolean; + 'creator': Attendee | null; + /** + * The timestamp of when the call was created + */ + 'createdAt': Date; + /** + * The timestamp of when the call was updated + */ + 'updatedAt': Date | null; + /** + * A preview of the attendees in the call + */ + 'attendeesPreview': AttendeesPreview; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "id", + "baseName": "id", + "type": "number", + "format": "int64" + }, + { + "name": "loggingType", + "baseName": "loggingType", + "type": "InteractionsCallLoggingTypeEnum", + "format": "" + }, + { + "name": "title", + "baseName": "title", + "type": "string", + "format": "" + }, + { + "name": "startTime", + "baseName": "startTime", + "type": "Date", + "format": "date-time" + }, + { + "name": "endTime", + "baseName": "endTime", + "type": "Date", + "format": "date-time" + }, + { + "name": "allDay", + "baseName": "allDay", + "type": "boolean", + "format": "" + }, + { + "name": "creator", + "baseName": "creator", + "type": "Attendee", + "format": "" + }, + { + "name": "createdAt", + "baseName": "createdAt", + "type": "Date", + "format": "date-time" + }, + { + "name": "updatedAt", + "baseName": "updatedAt", + "type": "Date", + "format": "date-time" + }, + { + "name": "attendeesPreview", + "baseName": "attendeesPreview", + "type": "AttendeesPreview", + "format": "" + } ]; + + static getAttributeTypeMap() { + return InteractionsCall.attributeTypeMap; + } + + public constructor() { + } +} + +export enum InteractionsCallLoggingTypeEnum { + Manual = 'manual' +} + diff --git a/src/v2/generated/models/InteractionsCallPaged.ts b/src/v2/generated/models/InteractionsCallPaged.ts new file mode 100644 index 0000000..47e0c1b --- /dev/null +++ b/src/v2/generated/models/InteractionsCallPaged.ts @@ -0,0 +1,51 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { InteractionsCall } from '../models/InteractionsCall.ts'; +import { PaginationWithTotalCount } from '../models/PaginationWithTotalCount.ts'; +import { HttpFile } from '../http/http.ts'; + +/** +* CallPaged model +*/ +export class InteractionsCallPaged { + /** + * A page of Call results + */ + 'data': Array; + 'pagination': PaginationWithTotalCount; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "data", + "baseName": "data", + "type": "Array", + "format": "" + }, + { + "name": "pagination", + "baseName": "pagination", + "type": "PaginationWithTotalCount", + "format": "" + } ]; + + static getAttributeTypeMap() { + return InteractionsCallPaged.attributeTypeMap; + } + + public constructor() { + } +} diff --git a/src/v2/generated/models/InteractionsChatMessage.ts b/src/v2/generated/models/InteractionsChatMessage.ts new file mode 100644 index 0000000..1158975 --- /dev/null +++ b/src/v2/generated/models/InteractionsChatMessage.ts @@ -0,0 +1,120 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { PersonData } from '../models/PersonData.ts'; +import { PersonDataPreview } from '../models/PersonDataPreview.ts'; +import { HttpFile } from '../http/http.ts'; + +export class InteractionsChatMessage { + /** + * The chat message\'s unique identifier + */ + 'id': number; + /** + * The timestamp of when the chat message was sent + */ + 'sentAt': Date; + /** + * Indicates how the interaction was added to Affinity: either manually by a user (\'manual\') or automatically through Affinity\'s capture process (\'automated\'). Currently, chat messages can only be logged as \'manual\'. + */ + 'loggingType': InteractionsChatMessageLoggingTypeEnum; + /** + * The direction of the chat message + */ + 'direction': InteractionsChatMessageDirectionEnum; + /** + * The creator of the chat message + */ + 'creator': PersonData; + /** + * The timestamp of when the chat message was created + */ + 'createdAt': Date; + /** + * The timestamp of when the chat message was updated + */ + 'updatedAt': Date | null; + /** + * A preview of the participants who are in the chat message + */ + 'participantsPreview': PersonDataPreview; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "id", + "baseName": "id", + "type": "number", + "format": "int64" + }, + { + "name": "sentAt", + "baseName": "sentAt", + "type": "Date", + "format": "date-time" + }, + { + "name": "loggingType", + "baseName": "loggingType", + "type": "InteractionsChatMessageLoggingTypeEnum", + "format": "" + }, + { + "name": "direction", + "baseName": "direction", + "type": "InteractionsChatMessageDirectionEnum", + "format": "" + }, + { + "name": "creator", + "baseName": "creator", + "type": "PersonData", + "format": "" + }, + { + "name": "createdAt", + "baseName": "createdAt", + "type": "Date", + "format": "date-time" + }, + { + "name": "updatedAt", + "baseName": "updatedAt", + "type": "Date", + "format": "date-time" + }, + { + "name": "participantsPreview", + "baseName": "participantsPreview", + "type": "PersonDataPreview", + "format": "" + } ]; + + static getAttributeTypeMap() { + return InteractionsChatMessage.attributeTypeMap; + } + + public constructor() { + } +} + +export enum InteractionsChatMessageLoggingTypeEnum { + Manual = 'manual' +} +export enum InteractionsChatMessageDirectionEnum { + Sent = 'sent', + Received = 'received' +} + diff --git a/src/v2/generated/models/InteractionsChatMessagePaged.ts b/src/v2/generated/models/InteractionsChatMessagePaged.ts new file mode 100644 index 0000000..c1932ae --- /dev/null +++ b/src/v2/generated/models/InteractionsChatMessagePaged.ts @@ -0,0 +1,51 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { InteractionsChatMessage } from '../models/InteractionsChatMessage.ts'; +import { PaginationWithTotalCount } from '../models/PaginationWithTotalCount.ts'; +import { HttpFile } from '../http/http.ts'; + +/** +* ChatMessagePaged model +*/ +export class InteractionsChatMessagePaged { + /** + * A page of ChatMessage results + */ + 'data': Array; + 'pagination': PaginationWithTotalCount; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "data", + "baseName": "data", + "type": "Array", + "format": "" + }, + { + "name": "pagination", + "baseName": "pagination", + "type": "PaginationWithTotalCount", + "format": "" + } ]; + + static getAttributeTypeMap() { + return InteractionsChatMessagePaged.attributeTypeMap; + } + + public constructor() { + } +} diff --git a/src/v2/generated/models/InteractionsEmail.ts b/src/v2/generated/models/InteractionsEmail.ts new file mode 100644 index 0000000..06d52d0 --- /dev/null +++ b/src/v2/generated/models/InteractionsEmail.ts @@ -0,0 +1,140 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { Attendee } from '../models/Attendee.ts'; +import { AttendeesPreview } from '../models/AttendeesPreview.ts'; +import { HttpFile } from '../http/http.ts'; + +export class InteractionsEmail { + /** + * The email\'s unique identifier + */ + 'id': number; + /** + * The timestamp of when the email was sent + */ + 'sentAt': Date; + /** + * Indicates how the interaction was added to Affinity: either manually by a user (\'manual\') or automatically through Affinity\'s capture process (\'automated\'). Currently, emails can only be logged as \'automated\'. + */ + 'loggingType': InteractionsEmailLoggingTypeEnum; + /** + * The direction of the email: \'sent\' if the email was sent by an internal user and \'received\' if the email was sent to an internal user. + */ + 'direction': InteractionsEmailDirectionEnum; + /** + * The email\'s subject + */ + 'subject': string | null; + /** + * The timestamp of when the email was created + */ + 'createdAt': Date; + /** + * The timestamp of when the email was updated + */ + 'updatedAt': Date | null; + /** + * The participant who sent the email + */ + '_from': Attendee; + /** + * A preview of the participants in the \'To\' field of the email + */ + 'toParticipantsPreview': AttendeesPreview; + /** + * A preview of the participants who are cc\'ed in the email + */ + 'ccParticipantsPreview': AttendeesPreview; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "id", + "baseName": "id", + "type": "number", + "format": "int64" + }, + { + "name": "sentAt", + "baseName": "sentAt", + "type": "Date", + "format": "date-time" + }, + { + "name": "loggingType", + "baseName": "loggingType", + "type": "InteractionsEmailLoggingTypeEnum", + "format": "" + }, + { + "name": "direction", + "baseName": "direction", + "type": "InteractionsEmailDirectionEnum", + "format": "" + }, + { + "name": "subject", + "baseName": "subject", + "type": "string", + "format": "" + }, + { + "name": "createdAt", + "baseName": "createdAt", + "type": "Date", + "format": "date-time" + }, + { + "name": "updatedAt", + "baseName": "updatedAt", + "type": "Date", + "format": "date-time" + }, + { + "name": "_from", + "baseName": "from", + "type": "Attendee", + "format": "" + }, + { + "name": "toParticipantsPreview", + "baseName": "toParticipantsPreview", + "type": "AttendeesPreview", + "format": "" + }, + { + "name": "ccParticipantsPreview", + "baseName": "ccParticipantsPreview", + "type": "AttendeesPreview", + "format": "" + } ]; + + static getAttributeTypeMap() { + return InteractionsEmail.attributeTypeMap; + } + + public constructor() { + } +} + +export enum InteractionsEmailLoggingTypeEnum { + Automated = 'automated' +} +export enum InteractionsEmailDirectionEnum { + Sent = 'sent', + Received = 'received' +} + diff --git a/src/v2/generated/models/InteractionsEmailPaged.ts b/src/v2/generated/models/InteractionsEmailPaged.ts new file mode 100644 index 0000000..8de8799 --- /dev/null +++ b/src/v2/generated/models/InteractionsEmailPaged.ts @@ -0,0 +1,51 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { InteractionsEmail } from '../models/InteractionsEmail.ts'; +import { PaginationWithTotalCount } from '../models/PaginationWithTotalCount.ts'; +import { HttpFile } from '../http/http.ts'; + +/** +* EmailPaged model +*/ +export class InteractionsEmailPaged { + /** + * A page of Email results + */ + 'data': Array; + 'pagination': PaginationWithTotalCount; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "data", + "baseName": "data", + "type": "Array", + "format": "" + }, + { + "name": "pagination", + "baseName": "pagination", + "type": "PaginationWithTotalCount", + "format": "" + } ]; + + static getAttributeTypeMap() { + return InteractionsEmailPaged.attributeTypeMap; + } + + public constructor() { + } +} diff --git a/src/v2/generated/models/InteractionsMeeting.ts b/src/v2/generated/models/InteractionsMeeting.ts new file mode 100644 index 0000000..f09bbee --- /dev/null +++ b/src/v2/generated/models/InteractionsMeeting.ts @@ -0,0 +1,141 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { Attendee } from '../models/Attendee.ts'; +import { AttendeesPreview } from '../models/AttendeesPreview.ts'; +import { HttpFile } from '../http/http.ts'; + +export class InteractionsMeeting { + /** + * The meeting\'s unique identifier + */ + 'id': number; + /** + * Indicates how the interaction was added to Affinity: either manually by a user (\'manual\') or automatically through Affinity\'s capture process (\'automated\'). + */ + 'loggingType': InteractionsMeetingLoggingTypeEnum; + /** + * The meeting\'s title + */ + 'title': string | null; + /** + * The timestamp of when the meeting starts + */ + 'startTime': Date; + /** + * The timestamp of when the meeting ends + */ + 'endTime': Date | null; + /** + * Whether the meeting is all day + */ + 'allDay': boolean; + 'creator': Attendee | null; + 'organizer': Attendee | null; + /** + * The timestamp of when the meeting was created + */ + 'createdAt': Date; + /** + * The timestamp of when the meeting was updated + */ + 'updatedAt': Date | null; + /** + * A preview of the attendees in the meeting + */ + 'attendeesPreview': AttendeesPreview; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "id", + "baseName": "id", + "type": "number", + "format": "int64" + }, + { + "name": "loggingType", + "baseName": "loggingType", + "type": "InteractionsMeetingLoggingTypeEnum", + "format": "" + }, + { + "name": "title", + "baseName": "title", + "type": "string", + "format": "" + }, + { + "name": "startTime", + "baseName": "startTime", + "type": "Date", + "format": "date-time" + }, + { + "name": "endTime", + "baseName": "endTime", + "type": "Date", + "format": "date-time" + }, + { + "name": "allDay", + "baseName": "allDay", + "type": "boolean", + "format": "" + }, + { + "name": "creator", + "baseName": "creator", + "type": "Attendee", + "format": "" + }, + { + "name": "organizer", + "baseName": "organizer", + "type": "Attendee", + "format": "" + }, + { + "name": "createdAt", + "baseName": "createdAt", + "type": "Date", + "format": "date-time" + }, + { + "name": "updatedAt", + "baseName": "updatedAt", + "type": "Date", + "format": "date-time" + }, + { + "name": "attendeesPreview", + "baseName": "attendeesPreview", + "type": "AttendeesPreview", + "format": "" + } ]; + + static getAttributeTypeMap() { + return InteractionsMeeting.attributeTypeMap; + } + + public constructor() { + } +} + +export enum InteractionsMeetingLoggingTypeEnum { + Automated = 'automated', + Manual = 'manual' +} + diff --git a/src/v2/generated/models/InteractionsMeetingPaged.ts b/src/v2/generated/models/InteractionsMeetingPaged.ts new file mode 100644 index 0000000..2b11425 --- /dev/null +++ b/src/v2/generated/models/InteractionsMeetingPaged.ts @@ -0,0 +1,51 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { InteractionsMeeting } from '../models/InteractionsMeeting.ts'; +import { PaginationWithTotalCount } from '../models/PaginationWithTotalCount.ts'; +import { HttpFile } from '../http/http.ts'; + +/** +* MeetingPaged model +*/ +export class InteractionsMeetingPaged { + /** + * A page of Meeting results + */ + 'data': Array; + 'pagination': PaginationWithTotalCount; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "data", + "baseName": "data", + "type": "Array", + "format": "" + }, + { + "name": "pagination", + "baseName": "pagination", + "type": "PaginationWithTotalCount", + "format": "" + } ]; + + static getAttributeTypeMap() { + return InteractionsMeetingPaged.attributeTypeMap; + } + + public constructor() { + } +} diff --git a/src/v2/generated/models/List.ts b/src/v2/generated/models/List.ts index f1a64db..31c2503 100644 --- a/src/v2/generated/models/List.ts +++ b/src/v2/generated/models/List.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/ListEntry.ts b/src/v2/generated/models/ListEntry.ts index facb6f0..8dc693d 100644 --- a/src/v2/generated/models/ListEntry.ts +++ b/src/v2/generated/models/ListEntry.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/ListEntryBatchOperationResponse.ts b/src/v2/generated/models/ListEntryBatchOperationResponse.ts index 57e8d0d..de785fb 100644 --- a/src/v2/generated/models/ListEntryBatchOperationResponse.ts +++ b/src/v2/generated/models/ListEntryBatchOperationResponse.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/ListEntryBatchOperationUpdateFields.ts b/src/v2/generated/models/ListEntryBatchOperationUpdateFields.ts index 745535f..3cc547e 100644 --- a/src/v2/generated/models/ListEntryBatchOperationUpdateFields.ts +++ b/src/v2/generated/models/ListEntryBatchOperationUpdateFields.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/ListEntryBatchOperationUpdateFieldsUpdatesInner.ts b/src/v2/generated/models/ListEntryBatchOperationUpdateFieldsUpdatesInner.ts index 16affcf..d72618f 100644 --- a/src/v2/generated/models/ListEntryBatchOperationUpdateFieldsUpdatesInner.ts +++ b/src/v2/generated/models/ListEntryBatchOperationUpdateFieldsUpdatesInner.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -29,7 +29,7 @@ export class ListEntryBatchOperationUpdateFieldsUpdatesInner { "name": "id", "baseName": "id", "type": "string", - "format": "string" + "format": "" }, { "name": "value", diff --git a/src/v2/generated/models/ListEntryBatchOperations.ts b/src/v2/generated/models/ListEntryBatchOperations.ts index ac09b65..0cfd605 100644 --- a/src/v2/generated/models/ListEntryBatchOperations.ts +++ b/src/v2/generated/models/ListEntryBatchOperations.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/ListEntryPaged.ts b/src/v2/generated/models/ListEntryPaged.ts index 07365cd..a5064c8 100644 --- a/src/v2/generated/models/ListEntryPaged.ts +++ b/src/v2/generated/models/ListEntryPaged.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/ListEntryWithEntity.ts b/src/v2/generated/models/ListEntryWithEntity.ts index 195db28..e2727fd 100644 --- a/src/v2/generated/models/ListEntryWithEntity.ts +++ b/src/v2/generated/models/ListEntryWithEntity.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/ListEntryWithEntityPaged.ts b/src/v2/generated/models/ListEntryWithEntityPaged.ts index f40ddf9..8de4b04 100644 --- a/src/v2/generated/models/ListEntryWithEntityPaged.ts +++ b/src/v2/generated/models/ListEntryWithEntityPaged.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/ListPaged.ts b/src/v2/generated/models/ListPaged.ts index a8dbc3c..696eebc 100644 --- a/src/v2/generated/models/ListPaged.ts +++ b/src/v2/generated/models/ListPaged.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/ListWithType.ts b/src/v2/generated/models/ListWithType.ts index 0b339a9..0d3a532 100644 --- a/src/v2/generated/models/ListWithType.ts +++ b/src/v2/generated/models/ListWithType.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/ListWithTypePaged.ts b/src/v2/generated/models/ListWithTypePaged.ts index 94d4c32..b34fbef 100644 --- a/src/v2/generated/models/ListWithTypePaged.ts +++ b/src/v2/generated/models/ListWithTypePaged.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/Location.ts b/src/v2/generated/models/Location.ts index ddc9ebf..6075749 100644 --- a/src/v2/generated/models/Location.ts +++ b/src/v2/generated/models/Location.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/LocationValue.ts b/src/v2/generated/models/LocationValue.ts index 8543e7f..48cc0b1 100644 --- a/src/v2/generated/models/LocationValue.ts +++ b/src/v2/generated/models/LocationValue.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/LocationsValue.ts b/src/v2/generated/models/LocationsValue.ts index 1dec3fd..1ec620b 100644 --- a/src/v2/generated/models/LocationsValue.ts +++ b/src/v2/generated/models/LocationsValue.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/Meeting.ts b/src/v2/generated/models/Meeting.ts index 3675b5b..23095e7 100644 --- a/src/v2/generated/models/Meeting.ts +++ b/src/v2/generated/models/Meeting.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -17,7 +17,7 @@ export class Meeting { /** * The type of interaction */ - 'type': string; + 'type': MeetingTypeEnum; /** * The meeting\'s unique identifier */ @@ -25,7 +25,7 @@ export class Meeting { /** * The meeting\'s title */ - 'title': string; + 'title': string | null; /** * Whether the meeting is an all-day event */ @@ -37,7 +37,7 @@ export class Meeting { /** * The meeting end time */ - 'endTime': Date; + 'endTime': Date | null; /** * People attending the meeting */ @@ -51,7 +51,7 @@ export class Meeting { { "name": "type", "baseName": "type", - "type": "string", + "type": "MeetingTypeEnum", "format": "" }, { @@ -98,3 +98,8 @@ export class Meeting { public constructor() { } } + +export enum MeetingTypeEnum { + Meeting = 'meeting' +} + diff --git a/src/v2/generated/models/MethodNotAllowedError.ts b/src/v2/generated/models/MethodNotAllowedError.ts index b3416b0..b93fa6c 100644 --- a/src/v2/generated/models/MethodNotAllowedError.ts +++ b/src/v2/generated/models/MethodNotAllowedError.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/ModelError.ts b/src/v2/generated/models/ModelError.ts index 0f7561c..8a6ef5a 100644 --- a/src/v2/generated/models/ModelError.ts +++ b/src/v2/generated/models/ModelError.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/NotAcceptableError.ts b/src/v2/generated/models/NotAcceptableError.ts index 01fa275..94bb134 100644 --- a/src/v2/generated/models/NotAcceptableError.ts +++ b/src/v2/generated/models/NotAcceptableError.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/NotFoundError.ts b/src/v2/generated/models/NotFoundError.ts index 5912592..9900269 100644 --- a/src/v2/generated/models/NotFoundError.ts +++ b/src/v2/generated/models/NotFoundError.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/NotFoundErrors.ts b/src/v2/generated/models/NotFoundErrors.ts index 9fc6cc4..f39c600 100644 --- a/src/v2/generated/models/NotFoundErrors.ts +++ b/src/v2/generated/models/NotFoundErrors.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/NotImplementedError.ts b/src/v2/generated/models/NotImplementedError.ts index 1092702..4c834a0 100644 --- a/src/v2/generated/models/NotImplementedError.ts +++ b/src/v2/generated/models/NotImplementedError.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/NotesAiNotetakerReplyNote.ts b/src/v2/generated/models/NotesAiNotetakerReplyNote.ts new file mode 100644 index 0000000..29f2141 --- /dev/null +++ b/src/v2/generated/models/NotesAiNotetakerReplyNote.ts @@ -0,0 +1,120 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { NotesBaseReplyParent } from '../models/NotesBaseReplyParent.ts'; +import { NotesContent } from '../models/NotesContent.ts'; +import { NotesMeetingInteraction } from '../models/NotesMeetingInteraction.ts'; +import { NotesPersonMention } from '../models/NotesPersonMention.ts'; +import { PersonData } from '../models/PersonData.ts'; +import { HttpFile } from '../http/http.ts'; + +export class NotesAiNotetakerReplyNote { + /** + * The id of the note + */ + 'id': number; + 'content': NotesContent; + 'creator': PersonData; + /** + * The mentions in the note + */ + 'mentions': Array; + /** + * The date and time the note was created + */ + 'createdAt': Date; + /** + * The date and time the note was last updated + */ + 'updatedAt': Date; + 'parent': NotesBaseReplyParent; + /** + * The type of the note + */ + 'type': NotesAiNotetakerReplyNoteTypeEnum; + /** + * The meeting this AI Notetaker was invited to. + */ + 'interaction'?: NotesMeetingInteraction; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "id", + "baseName": "id", + "type": "number", + "format": "int32" + }, + { + "name": "content", + "baseName": "content", + "type": "NotesContent", + "format": "" + }, + { + "name": "creator", + "baseName": "creator", + "type": "PersonData", + "format": "" + }, + { + "name": "mentions", + "baseName": "mentions", + "type": "Array", + "format": "" + }, + { + "name": "createdAt", + "baseName": "createdAt", + "type": "Date", + "format": "date-time" + }, + { + "name": "updatedAt", + "baseName": "updatedAt", + "type": "Date", + "format": "date-time" + }, + { + "name": "parent", + "baseName": "parent", + "type": "NotesBaseReplyParent", + "format": "" + }, + { + "name": "type", + "baseName": "type", + "type": "NotesAiNotetakerReplyNoteTypeEnum", + "format": "" + }, + { + "name": "interaction", + "baseName": "interaction", + "type": "NotesMeetingInteraction", + "format": "" + } ]; + + static getAttributeTypeMap() { + return NotesAiNotetakerReplyNote.attributeTypeMap; + } + + public constructor() { + } +} + +export enum NotesAiNotetakerReplyNoteTypeEnum { + AiNotetakerReply = 'ai-notetaker-reply' +} + diff --git a/src/v2/generated/models/NotesAiNotetakerRootNote.ts b/src/v2/generated/models/NotesAiNotetakerRootNote.ts new file mode 100644 index 0000000..bf919a3 --- /dev/null +++ b/src/v2/generated/models/NotesAiNotetakerRootNote.ts @@ -0,0 +1,154 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { NotesCompaniesPreview } from '../models/NotesCompaniesPreview.ts'; +import { NotesContent } from '../models/NotesContent.ts'; +import { NotesMeetingInteraction } from '../models/NotesMeetingInteraction.ts'; +import { NotesOpportunitiesPreview } from '../models/NotesOpportunitiesPreview.ts'; +import { NotesPermissionSettings } from '../models/NotesPermissionSettings.ts'; +import { NotesPersonMention } from '../models/NotesPersonMention.ts'; +import { NotesPersonsPreview } from '../models/NotesPersonsPreview.ts'; +import { PersonData } from '../models/PersonData.ts'; +import { HttpFile } from '../http/http.ts'; + +export class NotesAiNotetakerRootNote { + /** + * The id of the note + */ + 'id': number; + 'content': NotesContent; + 'creator': PersonData; + /** + * The mentions in the note + */ + 'mentions': Array; + /** + * The date and time the note was created + */ + 'createdAt': Date; + /** + * The date and time the note was last updated + */ + 'updatedAt': Date; + /** + * The number of replies to this note. This is only included if the `repliesCount` parameter is passed in the `includes` in the request and the note is not a reply itself. + */ + 'repliesCount'?: number; + 'permissions'?: NotesPermissionSettings; + 'opportunitiesPreview'?: NotesOpportunitiesPreview; + 'personsPreview'?: NotesPersonsPreview; + 'companiesPreview'?: NotesCompaniesPreview; + /** + * The type of the note + */ + 'type': NotesAiNotetakerRootNoteTypeEnum; + /** + * The meeting this AI Notetaker was invited to. + */ + 'interaction'?: NotesMeetingInteraction; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "id", + "baseName": "id", + "type": "number", + "format": "int32" + }, + { + "name": "content", + "baseName": "content", + "type": "NotesContent", + "format": "" + }, + { + "name": "creator", + "baseName": "creator", + "type": "PersonData", + "format": "" + }, + { + "name": "mentions", + "baseName": "mentions", + "type": "Array", + "format": "" + }, + { + "name": "createdAt", + "baseName": "createdAt", + "type": "Date", + "format": "date-time" + }, + { + "name": "updatedAt", + "baseName": "updatedAt", + "type": "Date", + "format": "date-time" + }, + { + "name": "repliesCount", + "baseName": "repliesCount", + "type": "number", + "format": "int32" + }, + { + "name": "permissions", + "baseName": "permissions", + "type": "NotesPermissionSettings", + "format": "" + }, + { + "name": "opportunitiesPreview", + "baseName": "opportunitiesPreview", + "type": "NotesOpportunitiesPreview", + "format": "" + }, + { + "name": "personsPreview", + "baseName": "personsPreview", + "type": "NotesPersonsPreview", + "format": "" + }, + { + "name": "companiesPreview", + "baseName": "companiesPreview", + "type": "NotesCompaniesPreview", + "format": "" + }, + { + "name": "type", + "baseName": "type", + "type": "NotesAiNotetakerRootNoteTypeEnum", + "format": "" + }, + { + "name": "interaction", + "baseName": "interaction", + "type": "NotesMeetingInteraction", + "format": "" + } ]; + + static getAttributeTypeMap() { + return NotesAiNotetakerRootNote.attributeTypeMap; + } + + public constructor() { + } +} + +export enum NotesAiNotetakerRootNoteTypeEnum { + AiNotetaker = 'ai-notetaker' +} + diff --git a/src/v2/generated/models/NotesBaseNote.ts b/src/v2/generated/models/NotesBaseNote.ts new file mode 100644 index 0000000..6226bb2 --- /dev/null +++ b/src/v2/generated/models/NotesBaseNote.ts @@ -0,0 +1,89 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { NotesContent } from '../models/NotesContent.ts'; +import { NotesPersonMention } from '../models/NotesPersonMention.ts'; +import { PersonData } from '../models/PersonData.ts'; +import { HttpFile } from '../http/http.ts'; + +/** +* An abstract base class for notes +*/ +export class NotesBaseNote { + /** + * The id of the note + */ + 'id': number; + 'content': NotesContent; + 'creator': PersonData; + /** + * The mentions in the note + */ + 'mentions': Array; + /** + * The date and time the note was created + */ + 'createdAt': Date; + /** + * The date and time the note was last updated + */ + 'updatedAt': Date | null; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "id", + "baseName": "id", + "type": "number", + "format": "int32" + }, + { + "name": "content", + "baseName": "content", + "type": "NotesContent", + "format": "" + }, + { + "name": "creator", + "baseName": "creator", + "type": "PersonData", + "format": "" + }, + { + "name": "mentions", + "baseName": "mentions", + "type": "Array", + "format": "" + }, + { + "name": "createdAt", + "baseName": "createdAt", + "type": "Date", + "format": "date-time" + }, + { + "name": "updatedAt", + "baseName": "updatedAt", + "type": "Date", + "format": "date-time" + } ]; + + static getAttributeTypeMap() { + return NotesBaseNote.attributeTypeMap; + } + + public constructor() { + } +} diff --git a/src/v2/generated/models/NotesBaseReply.ts b/src/v2/generated/models/NotesBaseReply.ts new file mode 100644 index 0000000..fb414c0 --- /dev/null +++ b/src/v2/generated/models/NotesBaseReply.ts @@ -0,0 +1,94 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { NotesBaseReplyParent } from '../models/NotesBaseReplyParent.ts'; +import { NotesContent } from '../models/NotesContent.ts'; +import { NotesPersonMention } from '../models/NotesPersonMention.ts'; +import { PersonData } from '../models/PersonData.ts'; +import { HttpFile } from '../http/http.ts'; + +export class NotesBaseReply { + /** + * The id of the note + */ + 'id': number; + 'content': NotesContent; + 'creator': PersonData; + /** + * The mentions in the note + */ + 'mentions': Array; + /** + * The date and time the note was created + */ + 'createdAt': Date; + /** + * The date and time the note was last updated + */ + 'updatedAt': Date; + 'parent': NotesBaseReplyParent; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "id", + "baseName": "id", + "type": "number", + "format": "int32" + }, + { + "name": "content", + "baseName": "content", + "type": "NotesContent", + "format": "" + }, + { + "name": "creator", + "baseName": "creator", + "type": "PersonData", + "format": "" + }, + { + "name": "mentions", + "baseName": "mentions", + "type": "Array", + "format": "" + }, + { + "name": "createdAt", + "baseName": "createdAt", + "type": "Date", + "format": "date-time" + }, + { + "name": "updatedAt", + "baseName": "updatedAt", + "type": "Date", + "format": "date-time" + }, + { + "name": "parent", + "baseName": "parent", + "type": "NotesBaseReplyParent", + "format": "" + } ]; + + static getAttributeTypeMap() { + return NotesBaseReply.attributeTypeMap; + } + + public constructor() { + } +} diff --git a/src/v2/generated/models/NotesBaseReplyParent.ts b/src/v2/generated/models/NotesBaseReplyParent.ts new file mode 100644 index 0000000..5fee380 --- /dev/null +++ b/src/v2/generated/models/NotesBaseReplyParent.ts @@ -0,0 +1,39 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { HttpFile } from '../http/http.ts'; + +export class NotesBaseReplyParent { + /** + * The id of the parent note + */ + 'id': number; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "id", + "baseName": "id", + "type": "number", + "format": "int32" + } ]; + + static getAttributeTypeMap() { + return NotesBaseReplyParent.attributeTypeMap; + } + + public constructor() { + } +} diff --git a/src/v2/generated/models/NotesBaseRootNote.ts b/src/v2/generated/models/NotesBaseRootNote.ts new file mode 100644 index 0000000..c535278 --- /dev/null +++ b/src/v2/generated/models/NotesBaseRootNote.ts @@ -0,0 +1,128 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { NotesCompaniesPreview } from '../models/NotesCompaniesPreview.ts'; +import { NotesContent } from '../models/NotesContent.ts'; +import { NotesOpportunitiesPreview } from '../models/NotesOpportunitiesPreview.ts'; +import { NotesPermissionSettings } from '../models/NotesPermissionSettings.ts'; +import { NotesPersonMention } from '../models/NotesPersonMention.ts'; +import { NotesPersonsPreview } from '../models/NotesPersonsPreview.ts'; +import { PersonData } from '../models/PersonData.ts'; +import { HttpFile } from '../http/http.ts'; + +export class NotesBaseRootNote { + /** + * The id of the note + */ + 'id': number; + 'content': NotesContent; + 'creator': PersonData; + /** + * The mentions in the note + */ + 'mentions': Array; + /** + * The date and time the note was created + */ + 'createdAt': Date; + /** + * The date and time the note was last updated + */ + 'updatedAt': Date; + /** + * The number of replies to this note. This is only included if the `repliesCount` parameter is passed in the `includes` in the request and the note is not a reply itself. + */ + 'repliesCount'?: number; + 'permissions'?: NotesPermissionSettings; + 'opportunitiesPreview'?: NotesOpportunitiesPreview; + 'personsPreview'?: NotesPersonsPreview; + 'companiesPreview'?: NotesCompaniesPreview; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "id", + "baseName": "id", + "type": "number", + "format": "int32" + }, + { + "name": "content", + "baseName": "content", + "type": "NotesContent", + "format": "" + }, + { + "name": "creator", + "baseName": "creator", + "type": "PersonData", + "format": "" + }, + { + "name": "mentions", + "baseName": "mentions", + "type": "Array", + "format": "" + }, + { + "name": "createdAt", + "baseName": "createdAt", + "type": "Date", + "format": "date-time" + }, + { + "name": "updatedAt", + "baseName": "updatedAt", + "type": "Date", + "format": "date-time" + }, + { + "name": "repliesCount", + "baseName": "repliesCount", + "type": "number", + "format": "int32" + }, + { + "name": "permissions", + "baseName": "permissions", + "type": "NotesPermissionSettings", + "format": "" + }, + { + "name": "opportunitiesPreview", + "baseName": "opportunitiesPreview", + "type": "NotesOpportunitiesPreview", + "format": "" + }, + { + "name": "personsPreview", + "baseName": "personsPreview", + "type": "NotesPersonsPreview", + "format": "" + }, + { + "name": "companiesPreview", + "baseName": "companiesPreview", + "type": "NotesCompaniesPreview", + "format": "" + } ]; + + static getAttributeTypeMap() { + return NotesBaseRootNote.attributeTypeMap; + } + + public constructor() { + } +} diff --git a/src/v2/generated/models/NotesCallInteraction.ts b/src/v2/generated/models/NotesCallInteraction.ts new file mode 100644 index 0000000..b76efb5 --- /dev/null +++ b/src/v2/generated/models/NotesCallInteraction.ts @@ -0,0 +1,57 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { HttpFile } from '../http/http.ts'; + +/** +* This is a Call (Event) object attached to a note +*/ +export class NotesCallInteraction { + /** + * The id of the Call (Event) + */ + 'id': number; + /** + * The type of the Interaction + */ + 'type': NotesCallInteractionTypeEnum; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "id", + "baseName": "id", + "type": "number", + "format": "int64" + }, + { + "name": "type", + "baseName": "type", + "type": "NotesCallInteractionTypeEnum", + "format": "" + } ]; + + static getAttributeTypeMap() { + return NotesCallInteraction.attributeTypeMap; + } + + public constructor() { + } +} + +export enum NotesCallInteractionTypeEnum { + Call = 'call' +} + diff --git a/src/v2/generated/models/NotesChatMessageInteraction.ts b/src/v2/generated/models/NotesChatMessageInteraction.ts new file mode 100644 index 0000000..afe8e05 --- /dev/null +++ b/src/v2/generated/models/NotesChatMessageInteraction.ts @@ -0,0 +1,57 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { HttpFile } from '../http/http.ts'; + +/** +* A ChatMessage object attached to a note +*/ +export class NotesChatMessageInteraction { + /** + * The id of the ChatMessage + */ + 'id': number; + /** + * The type of the Interaction + */ + 'type': NotesChatMessageInteractionTypeEnum; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "id", + "baseName": "id", + "type": "number", + "format": "int64" + }, + { + "name": "type", + "baseName": "type", + "type": "NotesChatMessageInteractionTypeEnum", + "format": "" + } ]; + + static getAttributeTypeMap() { + return NotesChatMessageInteraction.attributeTypeMap; + } + + public constructor() { + } +} + +export enum NotesChatMessageInteractionTypeEnum { + ChatMessage = 'chat-message' +} + diff --git a/src/v2/generated/models/NotesCompaniesPreview.ts b/src/v2/generated/models/NotesCompaniesPreview.ts new file mode 100644 index 0000000..5532e51 --- /dev/null +++ b/src/v2/generated/models/NotesCompaniesPreview.ts @@ -0,0 +1,53 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { CompanyData } from '../models/CompanyData.ts'; +import { HttpFile } from '../http/http.ts'; + +/** +* A preview for attached Companies on a Note +*/ +export class NotesCompaniesPreview { + /** + * Preview of attached Companies for a Note + */ + 'data'?: Array; + /** + * The total count of the collection parameter. + */ + 'totalCount'?: number; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "data", + "baseName": "data", + "type": "Array", + "format": "" + }, + { + "name": "totalCount", + "baseName": "totalCount", + "type": "number", + "format": "int64" + } ]; + + static getAttributeTypeMap() { + return NotesCompaniesPreview.attributeTypeMap; + } + + public constructor() { + } +} diff --git a/src/v2/generated/models/NotesContent.ts b/src/v2/generated/models/NotesContent.ts new file mode 100644 index 0000000..b2b0b06 --- /dev/null +++ b/src/v2/generated/models/NotesContent.ts @@ -0,0 +1,42 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { HttpFile } from '../http/http.ts'; + +/** +* A note content +*/ +export class NotesContent { + /** + * The HTML content of the note + */ + 'html': string | null; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "html", + "baseName": "html", + "type": "string", + "format": "" + } ]; + + static getAttributeTypeMap() { + return NotesContent.attributeTypeMap; + } + + public constructor() { + } +} diff --git a/src/v2/generated/models/NotesEmailInteraction.ts b/src/v2/generated/models/NotesEmailInteraction.ts new file mode 100644 index 0000000..20dc380 --- /dev/null +++ b/src/v2/generated/models/NotesEmailInteraction.ts @@ -0,0 +1,57 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { HttpFile } from '../http/http.ts'; + +/** +* This is an Email object attached to a note +*/ +export class NotesEmailInteraction { + /** + * The id of the Email + */ + 'id': number; + /** + * The type of the Interaction + */ + 'type': NotesEmailInteractionTypeEnum; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "id", + "baseName": "id", + "type": "number", + "format": "int64" + }, + { + "name": "type", + "baseName": "type", + "type": "NotesEmailInteractionTypeEnum", + "format": "" + } ]; + + static getAttributeTypeMap() { + return NotesEmailInteraction.attributeTypeMap; + } + + public constructor() { + } +} + +export enum NotesEmailInteractionTypeEnum { + Email = 'email' +} + diff --git a/src/v2/generated/models/NotesEntitiesNote.ts b/src/v2/generated/models/NotesEntitiesNote.ts new file mode 100644 index 0000000..cf5f135 --- /dev/null +++ b/src/v2/generated/models/NotesEntitiesNote.ts @@ -0,0 +1,143 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { NotesCompaniesPreview } from '../models/NotesCompaniesPreview.ts'; +import { NotesContent } from '../models/NotesContent.ts'; +import { NotesOpportunitiesPreview } from '../models/NotesOpportunitiesPreview.ts'; +import { NotesPermissionSettings } from '../models/NotesPermissionSettings.ts'; +import { NotesPersonMention } from '../models/NotesPersonMention.ts'; +import { NotesPersonsPreview } from '../models/NotesPersonsPreview.ts'; +import { PersonData } from '../models/PersonData.ts'; +import { HttpFile } from '../http/http.ts'; + +export class NotesEntitiesNote { + /** + * The id of the note + */ + 'id': number; + 'content': NotesContent; + 'creator': PersonData; + /** + * The mentions in the note + */ + 'mentions': Array; + /** + * The date and time the note was created + */ + 'createdAt': Date; + /** + * The date and time the note was last updated + */ + 'updatedAt': Date; + /** + * The number of replies to this note. This is only included if the `repliesCount` parameter is passed in the `includes` in the request and the note is not a reply itself. + */ + 'repliesCount'?: number; + 'permissions'?: NotesPermissionSettings; + 'opportunitiesPreview'?: NotesOpportunitiesPreview; + 'personsPreview'?: NotesPersonsPreview; + 'companiesPreview'?: NotesCompaniesPreview; + /** + * The type of the note + */ + 'type': NotesEntitiesNoteTypeEnum; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "id", + "baseName": "id", + "type": "number", + "format": "int32" + }, + { + "name": "content", + "baseName": "content", + "type": "NotesContent", + "format": "" + }, + { + "name": "creator", + "baseName": "creator", + "type": "PersonData", + "format": "" + }, + { + "name": "mentions", + "baseName": "mentions", + "type": "Array", + "format": "" + }, + { + "name": "createdAt", + "baseName": "createdAt", + "type": "Date", + "format": "date-time" + }, + { + "name": "updatedAt", + "baseName": "updatedAt", + "type": "Date", + "format": "date-time" + }, + { + "name": "repliesCount", + "baseName": "repliesCount", + "type": "number", + "format": "int32" + }, + { + "name": "permissions", + "baseName": "permissions", + "type": "NotesPermissionSettings", + "format": "" + }, + { + "name": "opportunitiesPreview", + "baseName": "opportunitiesPreview", + "type": "NotesOpportunitiesPreview", + "format": "" + }, + { + "name": "personsPreview", + "baseName": "personsPreview", + "type": "NotesPersonsPreview", + "format": "" + }, + { + "name": "companiesPreview", + "baseName": "companiesPreview", + "type": "NotesCompaniesPreview", + "format": "" + }, + { + "name": "type", + "baseName": "type", + "type": "NotesEntitiesNoteTypeEnum", + "format": "" + } ]; + + static getAttributeTypeMap() { + return NotesEntitiesNote.attributeTypeMap; + } + + public constructor() { + } +} + +export enum NotesEntitiesNoteTypeEnum { + Entities = 'entities' +} + diff --git a/src/v2/generated/models/NotesInteraction.ts b/src/v2/generated/models/NotesInteraction.ts new file mode 100644 index 0000000..e817199 --- /dev/null +++ b/src/v2/generated/models/NotesInteraction.ts @@ -0,0 +1,46 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { NotesCallInteraction } from '../models/NotesCallInteraction.ts'; +import { NotesChatMessageInteraction } from '../models/NotesChatMessageInteraction.ts'; +import { NotesEmailInteraction } from '../models/NotesEmailInteraction.ts'; +import { NotesMeetingInteraction } from '../models/NotesMeetingInteraction.ts'; +import { HttpFile } from '../http/http.ts'; + +/** +* An interaction attached to a Note. It can be a Meeting, a Call or an ChatMessage. +*/ +/** + * @type NotesInteraction + * Type + * @export + */ +export type NotesInteraction = NotesCallInteraction | NotesChatMessageInteraction | NotesEmailInteraction | NotesMeetingInteraction; + +/** +* @type NotesInteractionClass + * An interaction attached to a Note. It can be a Meeting, a Call or an ChatMessage. +* @export +*/ +export class NotesInteractionClass { + static readonly discriminator: string | undefined = "type"; + + static readonly mapping: {[index: string]: string} | undefined = { + "call": "NotesCallInteraction", + "chat-message": "NotesChatMessageInteraction", + "email": "NotesEmailInteraction", + "meeting": "NotesMeetingInteraction", + }; +} + + + diff --git a/src/v2/generated/models/NotesInteractionNote.ts b/src/v2/generated/models/NotesInteractionNote.ts new file mode 100644 index 0000000..da228fb --- /dev/null +++ b/src/v2/generated/models/NotesInteractionNote.ts @@ -0,0 +1,151 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { NotesCompaniesPreview } from '../models/NotesCompaniesPreview.ts'; +import { NotesContent } from '../models/NotesContent.ts'; +import { NotesInteraction } from '../models/NotesInteraction.ts'; +import { NotesOpportunitiesPreview } from '../models/NotesOpportunitiesPreview.ts'; +import { NotesPermissionSettings } from '../models/NotesPermissionSettings.ts'; +import { NotesPersonMention } from '../models/NotesPersonMention.ts'; +import { NotesPersonsPreview } from '../models/NotesPersonsPreview.ts'; +import { PersonData } from '../models/PersonData.ts'; +import { HttpFile } from '../http/http.ts'; + +export class NotesInteractionNote { + /** + * The id of the note + */ + 'id': number; + 'content': NotesContent; + 'creator': PersonData; + /** + * The mentions in the note + */ + 'mentions': Array; + /** + * The date and time the note was created + */ + 'createdAt': Date; + /** + * The date and time the note was last updated + */ + 'updatedAt': Date; + /** + * The number of replies to this note. This is only included if the `repliesCount` parameter is passed in the `includes` in the request and the note is not a reply itself. + */ + 'repliesCount'?: number; + 'permissions'?: NotesPermissionSettings; + 'opportunitiesPreview'?: NotesOpportunitiesPreview; + 'personsPreview'?: NotesPersonsPreview; + 'companiesPreview'?: NotesCompaniesPreview; + /** + * The type of the note + */ + 'type': NotesInteractionNoteTypeEnum; + 'interaction': NotesInteraction; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "id", + "baseName": "id", + "type": "number", + "format": "int32" + }, + { + "name": "content", + "baseName": "content", + "type": "NotesContent", + "format": "" + }, + { + "name": "creator", + "baseName": "creator", + "type": "PersonData", + "format": "" + }, + { + "name": "mentions", + "baseName": "mentions", + "type": "Array", + "format": "" + }, + { + "name": "createdAt", + "baseName": "createdAt", + "type": "Date", + "format": "date-time" + }, + { + "name": "updatedAt", + "baseName": "updatedAt", + "type": "Date", + "format": "date-time" + }, + { + "name": "repliesCount", + "baseName": "repliesCount", + "type": "number", + "format": "int32" + }, + { + "name": "permissions", + "baseName": "permissions", + "type": "NotesPermissionSettings", + "format": "" + }, + { + "name": "opportunitiesPreview", + "baseName": "opportunitiesPreview", + "type": "NotesOpportunitiesPreview", + "format": "" + }, + { + "name": "personsPreview", + "baseName": "personsPreview", + "type": "NotesPersonsPreview", + "format": "" + }, + { + "name": "companiesPreview", + "baseName": "companiesPreview", + "type": "NotesCompaniesPreview", + "format": "" + }, + { + "name": "type", + "baseName": "type", + "type": "NotesInteractionNoteTypeEnum", + "format": "" + }, + { + "name": "interaction", + "baseName": "interaction", + "type": "NotesInteraction", + "format": "" + } ]; + + static getAttributeTypeMap() { + return NotesInteractionNote.attributeTypeMap; + } + + public constructor() { + } +} + +export enum NotesInteractionNoteTypeEnum { + Interaction = 'interaction' +} + diff --git a/src/v2/generated/models/NotesMeetingInteraction.ts b/src/v2/generated/models/NotesMeetingInteraction.ts new file mode 100644 index 0000000..1aafbce --- /dev/null +++ b/src/v2/generated/models/NotesMeetingInteraction.ts @@ -0,0 +1,57 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { HttpFile } from '../http/http.ts'; + +/** +* This is a Meeting (Event) object attached to a note +*/ +export class NotesMeetingInteraction { + /** + * The id of the Meeting (Event) + */ + 'id': number; + /** + * The type of the Interaction + */ + 'type': NotesMeetingInteractionTypeEnum; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "id", + "baseName": "id", + "type": "number", + "format": "int64" + }, + { + "name": "type", + "baseName": "type", + "type": "NotesMeetingInteractionTypeEnum", + "format": "" + } ]; + + static getAttributeTypeMap() { + return NotesMeetingInteraction.attributeTypeMap; + } + + public constructor() { + } +} + +export enum NotesMeetingInteractionTypeEnum { + Meeting = 'meeting' +} + diff --git a/src/v2/generated/models/NotesNote.ts b/src/v2/generated/models/NotesNote.ts new file mode 100644 index 0000000..627e69c --- /dev/null +++ b/src/v2/generated/models/NotesNote.ts @@ -0,0 +1,49 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { NotesAiNotetakerReplyNote } from '../models/NotesAiNotetakerReplyNote.ts'; +import { NotesAiNotetakerRootNote } from '../models/NotesAiNotetakerRootNote.ts'; +import { NotesEntitiesNote } from '../models/NotesEntitiesNote.ts'; +import { NotesInteractionNote } from '../models/NotesInteractionNote.ts'; +import { NotesUserReplyNote } from '../models/NotesUserReplyNote.ts'; +import { HttpFile } from '../http/http.ts'; + +/** +* Note model +*/ +/** + * @type NotesNote + * Type + * @export + */ +export type NotesNote = NotesAiNotetakerReplyNote | NotesAiNotetakerRootNote | NotesEntitiesNote | NotesInteractionNote | NotesUserReplyNote; + +/** +* @type NotesNoteClass + * Note model +* @export +*/ +export class NotesNoteClass { + static readonly discriminator: string | undefined = "type"; + + static readonly mapping: {[index: string]: string} | undefined = { + "ai-notetaker": "NotesAiNotetakerRootNote", + "ai-notetaker-reply": "NotesAiNotetakerReplyNote", + "entities": "NotesEntitiesNote", + "interaction": "NotesInteractionNote", + "user-reply": "NotesUserReplyNote", + }; +} + + + + diff --git a/src/v2/generated/models/NotesNotesPaged.ts b/src/v2/generated/models/NotesNotesPaged.ts new file mode 100644 index 0000000..11e843b --- /dev/null +++ b/src/v2/generated/models/NotesNotesPaged.ts @@ -0,0 +1,51 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { NotesNote } from '../models/NotesNote.ts'; +import { PaginationWithTotalCount } from '../models/PaginationWithTotalCount.ts'; +import { HttpFile } from '../http/http.ts'; + +/** +* NotesPaged model +*/ +export class NotesNotesPaged { + /** + * A page of Note objects + */ + 'data': Array; + 'pagination': PaginationWithTotalCount; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "data", + "baseName": "data", + "type": "Array", + "format": "" + }, + { + "name": "pagination", + "baseName": "pagination", + "type": "PaginationWithTotalCount", + "format": "" + } ]; + + static getAttributeTypeMap() { + return NotesNotesPaged.attributeTypeMap; + } + + public constructor() { + } +} diff --git a/src/v2/generated/models/NotesOpportunitiesPreview.ts b/src/v2/generated/models/NotesOpportunitiesPreview.ts new file mode 100644 index 0000000..e623b7d --- /dev/null +++ b/src/v2/generated/models/NotesOpportunitiesPreview.ts @@ -0,0 +1,53 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { Opportunity } from '../models/Opportunity.ts'; +import { HttpFile } from '../http/http.ts'; + +/** +* A preview for attached Opportunities on a Note +*/ +export class NotesOpportunitiesPreview { + /** + * Preview of attached Opportunities for a Note + */ + 'data'?: Array; + /** + * The total count of the collection parameter. + */ + 'totalCount'?: number; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "data", + "baseName": "data", + "type": "Array", + "format": "" + }, + { + "name": "totalCount", + "baseName": "totalCount", + "type": "number", + "format": "int64" + } ]; + + static getAttributeTypeMap() { + return NotesOpportunitiesPreview.attributeTypeMap; + } + + public constructor() { + } +} diff --git a/src/v2/generated/models/NotesPermissionSettings.ts b/src/v2/generated/models/NotesPermissionSettings.ts new file mode 100644 index 0000000..b5683d9 --- /dev/null +++ b/src/v2/generated/models/NotesPermissionSettings.ts @@ -0,0 +1,57 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { PersonData } from '../models/PersonData.ts'; +import { HttpFile } from '../http/http.ts'; + +/** +* The permission settings of a note +*/ +export class NotesPermissionSettings { + /** + * The sharing type of the note + */ + 'sharingType': NotesPermissionSettingsSharingTypeEnum; + 'owner': PersonData; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "sharingType", + "baseName": "sharingType", + "type": "NotesPermissionSettingsSharingTypeEnum", + "format": "" + }, + { + "name": "owner", + "baseName": "owner", + "type": "PersonData", + "format": "" + } ]; + + static getAttributeTypeMap() { + return NotesPermissionSettings.attributeTypeMap; + } + + public constructor() { + } +} + +export enum NotesPermissionSettingsSharingTypeEnum { + Private = 'private', + Public = 'public', + Custom = 'custom' +} + diff --git a/src/v2/generated/models/NotesPersonMention.ts b/src/v2/generated/models/NotesPersonMention.ts new file mode 100644 index 0000000..0ac7b1d --- /dev/null +++ b/src/v2/generated/models/NotesPersonMention.ts @@ -0,0 +1,65 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { PersonData } from '../models/PersonData.ts'; +import { HttpFile } from '../http/http.ts'; + +/** +* A person mentioned in a note. +*/ +export class NotesPersonMention { + /** + * The id of the mention + */ + 'id': number; + /** + * The type of mention + */ + 'type': NotesPersonMentionTypeEnum; + 'person': PersonData; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "id", + "baseName": "id", + "type": "number", + "format": "int32" + }, + { + "name": "type", + "baseName": "type", + "type": "NotesPersonMentionTypeEnum", + "format": "" + }, + { + "name": "person", + "baseName": "person", + "type": "PersonData", + "format": "" + } ]; + + static getAttributeTypeMap() { + return NotesPersonMention.attributeTypeMap; + } + + public constructor() { + } +} + +export enum NotesPersonMentionTypeEnum { + Person = 'person' +} + diff --git a/src/v2/generated/models/NotesPersonsPreview.ts b/src/v2/generated/models/NotesPersonsPreview.ts new file mode 100644 index 0000000..503b15d --- /dev/null +++ b/src/v2/generated/models/NotesPersonsPreview.ts @@ -0,0 +1,53 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { PersonData } from '../models/PersonData.ts'; +import { HttpFile } from '../http/http.ts'; + +/** +* A preview for attached Persons on a Note +*/ +export class NotesPersonsPreview { + /** + * Preview of attached Persons for a Note + */ + 'data'?: Array; + /** + * The total count of the collection parameter. + */ + 'totalCount'?: number; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "data", + "baseName": "data", + "type": "Array", + "format": "" + }, + { + "name": "totalCount", + "baseName": "totalCount", + "type": "number", + "format": "int64" + } ]; + + static getAttributeTypeMap() { + return NotesPersonsPreview.attributeTypeMap; + } + + public constructor() { + } +} diff --git a/src/v2/generated/models/NotesRepliesPaged.ts b/src/v2/generated/models/NotesRepliesPaged.ts new file mode 100644 index 0000000..20cd6e1 --- /dev/null +++ b/src/v2/generated/models/NotesRepliesPaged.ts @@ -0,0 +1,51 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { NotesReply } from '../models/NotesReply.ts'; +import { PaginationWithTotalCount } from '../models/PaginationWithTotalCount.ts'; +import { HttpFile } from '../http/http.ts'; + +/** +* Replies for a Note +*/ +export class NotesRepliesPaged { + /** + * A page of Note Replies + */ + 'data': Array; + 'pagination': PaginationWithTotalCount; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "data", + "baseName": "data", + "type": "Array", + "format": "" + }, + { + "name": "pagination", + "baseName": "pagination", + "type": "PaginationWithTotalCount", + "format": "" + } ]; + + static getAttributeTypeMap() { + return NotesRepliesPaged.attributeTypeMap; + } + + public constructor() { + } +} diff --git a/src/v2/generated/models/NotesReply.ts b/src/v2/generated/models/NotesReply.ts new file mode 100644 index 0000000..9006772 --- /dev/null +++ b/src/v2/generated/models/NotesReply.ts @@ -0,0 +1,40 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { NotesAiNotetakerReplyNote } from '../models/NotesAiNotetakerReplyNote.ts'; +import { NotesUserReplyNote } from '../models/NotesUserReplyNote.ts'; +import { HttpFile } from '../http/http.ts'; + +/** +* A Reply to a Note, created by a User or AI Notetaker. +*/ +/** + * @type NotesReply + * Type + * @export + */ +export type NotesReply = NotesAiNotetakerReplyNote | NotesUserReplyNote; + +/** +* @type NotesReplyClass + * A Reply to a Note, created by a User or AI Notetaker. +* @export +*/ +export class NotesReplyClass { + static readonly discriminator: string | undefined = "type"; + + static readonly mapping: {[index: string]: string} | undefined = { + "ai-notetaker-reply": "NotesAiNotetakerReplyNote", + "user-reply": "NotesUserReplyNote", + }; +} + diff --git a/src/v2/generated/models/NotesUserReplyNote.ts b/src/v2/generated/models/NotesUserReplyNote.ts new file mode 100644 index 0000000..ee3e395 --- /dev/null +++ b/src/v2/generated/models/NotesUserReplyNote.ts @@ -0,0 +1,109 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { NotesBaseReplyParent } from '../models/NotesBaseReplyParent.ts'; +import { NotesContent } from '../models/NotesContent.ts'; +import { NotesPersonMention } from '../models/NotesPersonMention.ts'; +import { PersonData } from '../models/PersonData.ts'; +import { HttpFile } from '../http/http.ts'; + +export class NotesUserReplyNote { + /** + * The id of the note + */ + 'id': number; + 'content': NotesContent; + 'creator': PersonData; + /** + * The mentions in the note + */ + 'mentions': Array; + /** + * The date and time the note was created + */ + 'createdAt': Date; + /** + * The date and time the note was last updated + */ + 'updatedAt': Date; + 'parent': NotesBaseReplyParent; + /** + * The type of the note + */ + 'type': NotesUserReplyNoteTypeEnum; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "id", + "baseName": "id", + "type": "number", + "format": "int32" + }, + { + "name": "content", + "baseName": "content", + "type": "NotesContent", + "format": "" + }, + { + "name": "creator", + "baseName": "creator", + "type": "PersonData", + "format": "" + }, + { + "name": "mentions", + "baseName": "mentions", + "type": "Array", + "format": "" + }, + { + "name": "createdAt", + "baseName": "createdAt", + "type": "Date", + "format": "date-time" + }, + { + "name": "updatedAt", + "baseName": "updatedAt", + "type": "Date", + "format": "date-time" + }, + { + "name": "parent", + "baseName": "parent", + "type": "NotesBaseReplyParent", + "format": "" + }, + { + "name": "type", + "baseName": "type", + "type": "NotesUserReplyNoteTypeEnum", + "format": "" + } ]; + + static getAttributeTypeMap() { + return NotesUserReplyNote.attributeTypeMap; + } + + public constructor() { + } +} + +export enum NotesUserReplyNoteTypeEnum { + UserReply = 'user-reply' +} + diff --git a/src/v2/generated/models/ObjectSerializer.ts b/src/v2/generated/models/ObjectSerializer.ts index 4ba5504..2f1f760 100644 --- a/src/v2/generated/models/ObjectSerializer.ts +++ b/src/v2/generated/models/ObjectSerializer.ts @@ -1,4 +1,5 @@ export * from '../models/Attendee.ts'; +export * from '../models/AttendeesPreview.ts'; export * from '../models/AuthenticationError.ts'; export * from '../models/AuthorizationError.ts'; export * from '../models/AuthorizationErrors.ts'; @@ -8,7 +9,15 @@ export * from '../models/CompaniesValue.ts'; export * from '../models/CompaniesValueUpdate.ts'; export * from '../models/Company.ts'; export * from '../models/CompanyData.ts'; +export * from '../models/CompanyDataPaged.ts'; export * from '../models/CompanyListEntry.ts'; +export * from '../models/CompanyMergeRequest.ts'; +export * from '../models/CompanyMergeResponse.ts'; +export * from '../models/CompanyMergeState.ts'; +export * from '../models/CompanyMergeStatePaged.ts'; +export * from '../models/CompanyMergeTask.ts'; +export * from '../models/CompanyMergeTaskPaged.ts'; +export * from '../models/CompanyMergeTaskResultsSummary.ts'; export * from '../models/CompanyPaged.ts'; export * from '../models/CompanyReference.ts'; export * from '../models/CompanyValue.ts'; @@ -35,10 +44,16 @@ export * from '../models/FloatsValue.ts'; export * from '../models/FormulaNumber.ts'; export * from '../models/FormulaValue.ts'; export * from '../models/Grant.ts'; -export * from '../models/InlineObject.ts'; -export * from '../models/InlineObjectErrorsInner.ts'; export * from '../models/Interaction.ts'; export * from '../models/InteractionValue.ts'; +export * from '../models/InteractionsCall.ts'; +export * from '../models/InteractionsCallPaged.ts'; +export * from '../models/InteractionsChatMessage.ts'; +export * from '../models/InteractionsChatMessagePaged.ts'; +export * from '../models/InteractionsEmail.ts'; +export * from '../models/InteractionsEmailPaged.ts'; +export * from '../models/InteractionsMeeting.ts'; +export * from '../models/InteractionsMeetingPaged.ts'; export * from '../models/List.ts'; export * from '../models/ListEntry.ts'; export * from '../models/ListEntryBatchOperationResponse.ts'; @@ -61,14 +76,47 @@ export * from '../models/NotAcceptableError.ts'; export * from '../models/NotFoundError.ts'; export * from '../models/NotFoundErrors.ts'; export * from '../models/NotImplementedError.ts'; +export * from '../models/NotesAiNotetakerReplyNote.ts'; +export * from '../models/NotesAiNotetakerRootNote.ts'; +export * from '../models/NotesBaseNote.ts'; +export * from '../models/NotesBaseReply.ts'; +export * from '../models/NotesBaseReplyParent.ts'; +export * from '../models/NotesBaseRootNote.ts'; +export * from '../models/NotesCallInteraction.ts'; +export * from '../models/NotesChatMessageInteraction.ts'; +export * from '../models/NotesCompaniesPreview.ts'; +export * from '../models/NotesContent.ts'; +export * from '../models/NotesEmailInteraction.ts'; +export * from '../models/NotesEntitiesNote.ts'; +export * from '../models/NotesInteraction.ts'; +export * from '../models/NotesInteractionNote.ts'; +export * from '../models/NotesMeetingInteraction.ts'; +export * from '../models/NotesNote.ts'; +export * from '../models/NotesNotesPaged.ts'; +export * from '../models/NotesOpportunitiesPreview.ts'; +export * from '../models/NotesPermissionSettings.ts'; +export * from '../models/NotesPersonMention.ts'; +export * from '../models/NotesPersonsPreview.ts'; +export * from '../models/NotesRepliesPaged.ts'; +export * from '../models/NotesReply.ts'; +export * from '../models/NotesUserReplyNote.ts'; export * from '../models/Opportunity.ts'; export * from '../models/OpportunityListEntry.ts'; export * from '../models/OpportunityPaged.ts'; export * from '../models/OpportunityWithFields.ts'; export * from '../models/Pagination.ts'; +export * from '../models/PaginationWithTotalCount.ts'; export * from '../models/Person.ts'; export * from '../models/PersonData.ts'; +export * from '../models/PersonDataPaged.ts'; +export * from '../models/PersonDataPreview.ts'; export * from '../models/PersonListEntry.ts'; +export * from '../models/PersonMergeRequest.ts'; +export * from '../models/PersonMergeResponse.ts'; +export * from '../models/PersonMergeState.ts'; +export * from '../models/PersonMergeStatePaged.ts'; +export * from '../models/PersonMergeTask.ts'; +export * from '../models/PersonMergeTaskPaged.ts'; export * from '../models/PersonPaged.ts'; export * from '../models/PersonReference.ts'; export * from '../models/PersonValue.ts'; @@ -81,6 +129,8 @@ export * from '../models/RankedDropdownReference.ts'; export * from '../models/RankedDropdownValue.ts'; export * from '../models/RankedDropdownValueUpdate.ts'; export * from '../models/RateLimitError.ts'; +export * from '../models/Responses400.ts'; +export * from '../models/Responses400ErrorsInner.ts'; export * from '../models/SavedView.ts'; export * from '../models/SavedViewPaged.ts'; export * from '../models/ServerError.ts'; @@ -94,6 +144,7 @@ export * from '../models/ValidationError.ts'; export * from '../models/WhoAmI.ts'; import { Attendee } from '../models/Attendee.ts'; +import { AttendeesPreview } from '../models/AttendeesPreview.ts'; import { AuthenticationError, AuthenticationErrorCodeEnum } from '../models/AuthenticationError.ts'; import { AuthorizationError, AuthorizationErrorCodeEnum } from '../models/AuthorizationError.ts'; import { AuthorizationErrors } from '../models/AuthorizationErrors.ts'; @@ -103,7 +154,15 @@ import { CompaniesValue, CompaniesValueTypeEnum } from '../models/CompaniesVa import { CompaniesValueUpdate, CompaniesValueUpdateTypeEnum } from '../models/CompaniesValueUpdate.ts'; import { Company } from '../models/Company.ts'; import { CompanyData } from '../models/CompanyData.ts'; +import { CompanyDataPaged } from '../models/CompanyDataPaged.ts'; import { CompanyListEntry , CompanyListEntryTypeEnum } from '../models/CompanyListEntry.ts'; +import { CompanyMergeRequest } from '../models/CompanyMergeRequest.ts'; +import { CompanyMergeResponse } from '../models/CompanyMergeResponse.ts'; +import { CompanyMergeState , CompanyMergeStateStatusEnum } from '../models/CompanyMergeState.ts'; +import { CompanyMergeStatePaged } from '../models/CompanyMergeStatePaged.ts'; +import { CompanyMergeTask , CompanyMergeTaskStatusEnum } from '../models/CompanyMergeTask.ts'; +import { CompanyMergeTaskPaged } from '../models/CompanyMergeTaskPaged.ts'; +import { CompanyMergeTaskResultsSummary } from '../models/CompanyMergeTaskResultsSummary.ts'; import { CompanyPaged } from '../models/CompanyPaged.ts'; import { CompanyReference } from '../models/CompanyReference.ts'; import { CompanyValue, CompanyValueTypeEnum } from '../models/CompanyValue.ts'; @@ -130,10 +189,16 @@ import { FloatsValue, FloatsValueTypeEnum } from '../models/FloatsValue.ts'; import { FormulaNumber } from '../models/FormulaNumber.ts'; import { FormulaValue, FormulaValueTypeEnum } from '../models/FormulaValue.ts'; import { Grant, GrantTypeEnum } from '../models/Grant.ts'; -import { InlineObject } from '../models/InlineObject.ts'; -import { InlineObjectErrorsInnerClass } from '../models/InlineObjectErrorsInner.ts'; import { InteractionClass } from '../models/Interaction.ts'; import { InteractionValue, InteractionValueTypeEnum } from '../models/InteractionValue.ts'; +import { InteractionsCall , InteractionsCallLoggingTypeEnum } from '../models/InteractionsCall.ts'; +import { InteractionsCallPaged } from '../models/InteractionsCallPaged.ts'; +import { InteractionsChatMessage , InteractionsChatMessageLoggingTypeEnum , InteractionsChatMessageDirectionEnum } from '../models/InteractionsChatMessage.ts'; +import { InteractionsChatMessagePaged } from '../models/InteractionsChatMessagePaged.ts'; +import { InteractionsEmail , InteractionsEmailLoggingTypeEnum , InteractionsEmailDirectionEnum } from '../models/InteractionsEmail.ts'; +import { InteractionsEmailPaged } from '../models/InteractionsEmailPaged.ts'; +import { InteractionsMeeting , InteractionsMeetingLoggingTypeEnum } from '../models/InteractionsMeeting.ts'; +import { InteractionsMeetingPaged } from '../models/InteractionsMeetingPaged.ts'; import { List } from '../models/List.ts'; import { ListEntry } from '../models/ListEntry.ts'; import { ListEntryBatchOperationResponse } from '../models/ListEntryBatchOperationResponse.ts'; @@ -149,21 +214,54 @@ import { ListWithTypePaged } from '../models/ListWithTypePaged.ts'; import { Location } from '../models/Location.ts'; import { LocationValue, LocationValueTypeEnum } from '../models/LocationValue.ts'; import { LocationsValue, LocationsValueTypeEnum } from '../models/LocationsValue.ts'; -import { Meeting } from '../models/Meeting.ts'; +import { Meeting, MeetingTypeEnum } from '../models/Meeting.ts'; import { MethodNotAllowedError, MethodNotAllowedErrorCodeEnum } from '../models/MethodNotAllowedError.ts'; import { ModelErrorClass } from '../models/ModelError.ts'; import { NotAcceptableError, NotAcceptableErrorCodeEnum } from '../models/NotAcceptableError.ts'; import { NotFoundError, NotFoundErrorCodeEnum } from '../models/NotFoundError.ts'; import { NotFoundErrors } from '../models/NotFoundErrors.ts'; import { NotImplementedError, NotImplementedErrorCodeEnum } from '../models/NotImplementedError.ts'; +import { NotesAiNotetakerReplyNote , NotesAiNotetakerReplyNoteTypeEnum } from '../models/NotesAiNotetakerReplyNote.ts'; +import { NotesAiNotetakerRootNote , NotesAiNotetakerRootNoteTypeEnum } from '../models/NotesAiNotetakerRootNote.ts'; +import { NotesBaseNote } from '../models/NotesBaseNote.ts'; +import { NotesBaseReply } from '../models/NotesBaseReply.ts'; +import { NotesBaseReplyParent } from '../models/NotesBaseReplyParent.ts'; +import { NotesBaseRootNote } from '../models/NotesBaseRootNote.ts'; +import { NotesCallInteraction , NotesCallInteractionTypeEnum } from '../models/NotesCallInteraction.ts'; +import { NotesChatMessageInteraction , NotesChatMessageInteractionTypeEnum } from '../models/NotesChatMessageInteraction.ts'; +import { NotesCompaniesPreview } from '../models/NotesCompaniesPreview.ts'; +import { NotesContent } from '../models/NotesContent.ts'; +import { NotesEmailInteraction , NotesEmailInteractionTypeEnum } from '../models/NotesEmailInteraction.ts'; +import { NotesEntitiesNote , NotesEntitiesNoteTypeEnum } from '../models/NotesEntitiesNote.ts'; +import { NotesInteractionClass } from '../models/NotesInteraction.ts'; +import { NotesInteractionNote , NotesInteractionNoteTypeEnum } from '../models/NotesInteractionNote.ts'; +import { NotesMeetingInteraction , NotesMeetingInteractionTypeEnum } from '../models/NotesMeetingInteraction.ts'; +import { NotesNoteClass } from '../models/NotesNote.ts'; +import { NotesNotesPaged } from '../models/NotesNotesPaged.ts'; +import { NotesOpportunitiesPreview } from '../models/NotesOpportunitiesPreview.ts'; +import { NotesPermissionSettings, NotesPermissionSettingsSharingTypeEnum } from '../models/NotesPermissionSettings.ts'; +import { NotesPersonMention , NotesPersonMentionTypeEnum } from '../models/NotesPersonMention.ts'; +import { NotesPersonsPreview } from '../models/NotesPersonsPreview.ts'; +import { NotesRepliesPaged } from '../models/NotesRepliesPaged.ts'; +import { NotesReplyClass } from '../models/NotesReply.ts'; +import { NotesUserReplyNote , NotesUserReplyNoteTypeEnum } from '../models/NotesUserReplyNote.ts'; import { Opportunity } from '../models/Opportunity.ts'; import { OpportunityListEntry , OpportunityListEntryTypeEnum } from '../models/OpportunityListEntry.ts'; import { OpportunityPaged } from '../models/OpportunityPaged.ts'; import { OpportunityWithFields } from '../models/OpportunityWithFields.ts'; import { Pagination } from '../models/Pagination.ts'; +import { PaginationWithTotalCount } from '../models/PaginationWithTotalCount.ts'; import { Person , PersonTypeEnum } from '../models/Person.ts'; import { PersonData , PersonDataTypeEnum } from '../models/PersonData.ts'; +import { PersonDataPaged } from '../models/PersonDataPaged.ts'; +import { PersonDataPreview } from '../models/PersonDataPreview.ts'; import { PersonListEntry , PersonListEntryTypeEnum } from '../models/PersonListEntry.ts'; +import { PersonMergeRequest } from '../models/PersonMergeRequest.ts'; +import { PersonMergeResponse } from '../models/PersonMergeResponse.ts'; +import { PersonMergeState , PersonMergeStateStatusEnum } from '../models/PersonMergeState.ts'; +import { PersonMergeStatePaged } from '../models/PersonMergeStatePaged.ts'; +import { PersonMergeTask , PersonMergeTaskStatusEnum } from '../models/PersonMergeTask.ts'; +import { PersonMergeTaskPaged } from '../models/PersonMergeTaskPaged.ts'; import { PersonPaged } from '../models/PersonPaged.ts'; import { PersonReference } from '../models/PersonReference.ts'; import { PersonValue, PersonValueTypeEnum } from '../models/PersonValue.ts'; @@ -176,6 +274,8 @@ import { RankedDropdownReference } from '../models/RankedDropdownReference.ts'; import { RankedDropdownValue, RankedDropdownValueTypeEnum } from '../models/RankedDropdownValue.ts'; import { RankedDropdownValueUpdate, RankedDropdownValueUpdateTypeEnum } from '../models/RankedDropdownValueUpdate.ts'; import { RateLimitError, RateLimitErrorCodeEnum } from '../models/RateLimitError.ts'; +import { Responses400 } from '../models/Responses400.ts'; +import { Responses400ErrorsInnerClass } from '../models/Responses400ErrorsInner.ts'; import { SavedView , SavedViewTypeEnum } from '../models/SavedView.ts'; import { SavedViewPaged } from '../models/SavedViewPaged.ts'; import { ServerError, ServerErrorCodeEnum } from '../models/ServerError.ts'; @@ -209,6 +309,8 @@ let enumsMap: Set = new Set([ "CompaniesValueTypeEnum", "CompaniesValueUpdateTypeEnum", "CompanyListEntryTypeEnum", + "CompanyMergeStateStatusEnum", + "CompanyMergeTaskStatusEnum", "CompanyValueTypeEnum", "CompanyValueUpdateTypeEnum", "ConflictErrorCodeEnum", @@ -229,24 +331,47 @@ let enumsMap: Set = new Set([ "FloatsValueTypeEnum", "FormulaValueTypeEnum", "GrantTypeEnum", - "InlineObjectErrorsInnerCodeEnum", + "InteractionTypeEnum", "InteractionDirectionEnum", "InteractionValueTypeEnum", + "InteractionsCallLoggingTypeEnum", + "InteractionsChatMessageLoggingTypeEnum", + "InteractionsChatMessageDirectionEnum", + "InteractionsEmailLoggingTypeEnum", + "InteractionsEmailDirectionEnum", + "InteractionsMeetingLoggingTypeEnum", "ListEntryBatchOperationUpdateFieldsOperationEnum", "ListEntryBatchOperations", "ListEntryWithEntityTypeEnum", "ListWithTypeTypeEnum", "LocationValueTypeEnum", "LocationsValueTypeEnum", + "MeetingTypeEnum", "MethodNotAllowedErrorCodeEnum", "ModelErrorCodeEnum", "NotAcceptableErrorCodeEnum", "NotFoundErrorCodeEnum", "NotImplementedErrorCodeEnum", + "NotesAiNotetakerReplyNoteTypeEnum", + "NotesAiNotetakerRootNoteTypeEnum", + "NotesCallInteractionTypeEnum", + "NotesChatMessageInteractionTypeEnum", + "NotesEmailInteractionTypeEnum", + "NotesEntitiesNoteTypeEnum", + "NotesInteractionTypeEnum", + "NotesInteractionNoteTypeEnum", + "NotesMeetingInteractionTypeEnum", + "NotesNoteTypeEnum", + "NotesPermissionSettingsSharingTypeEnum", + "NotesPersonMentionTypeEnum", + "NotesReplyTypeEnum", + "NotesUserReplyNoteTypeEnum", "OpportunityListEntryTypeEnum", "PersonTypeEnum", "PersonDataTypeEnum", "PersonListEntryTypeEnum", + "PersonMergeStateStatusEnum", + "PersonMergeTaskStatusEnum", "PersonValueTypeEnum", "PersonValueUpdateTypeEnum", "PersonsValueTypeEnum", @@ -255,6 +380,7 @@ let enumsMap: Set = new Set([ "RankedDropdownValueTypeEnum", "RankedDropdownValueUpdateTypeEnum", "RateLimitErrorCodeEnum", + "Responses400ErrorsInnerCodeEnum", "SavedViewTypeEnum", "ServerErrorCodeEnum", "TextValueTypeEnum", @@ -266,6 +392,7 @@ let enumsMap: Set = new Set([ let typeMap: {[index: string]: any} = { "Attendee": Attendee, + "AttendeesPreview": AttendeesPreview, "AuthenticationError": AuthenticationError, "AuthorizationError": AuthorizationError, "AuthorizationErrors": AuthorizationErrors, @@ -275,7 +402,15 @@ let typeMap: {[index: string]: any} = { "CompaniesValueUpdate": CompaniesValueUpdate, "Company": Company, "CompanyData": CompanyData, + "CompanyDataPaged": CompanyDataPaged, "CompanyListEntry": CompanyListEntry, + "CompanyMergeRequest": CompanyMergeRequest, + "CompanyMergeResponse": CompanyMergeResponse, + "CompanyMergeState": CompanyMergeState, + "CompanyMergeStatePaged": CompanyMergeStatePaged, + "CompanyMergeTask": CompanyMergeTask, + "CompanyMergeTaskPaged": CompanyMergeTaskPaged, + "CompanyMergeTaskResultsSummary": CompanyMergeTaskResultsSummary, "CompanyPaged": CompanyPaged, "CompanyReference": CompanyReference, "CompanyValue": CompanyValue, @@ -302,10 +437,16 @@ let typeMap: {[index: string]: any} = { "FormulaNumber": FormulaNumber, "FormulaValue": FormulaValue, "Grant": Grant, - "InlineObject": InlineObject, - "InlineObjectErrorsInner": InlineObjectErrorsInnerClass, "Interaction": InteractionClass, "InteractionValue": InteractionValue, + "InteractionsCall": InteractionsCall, + "InteractionsCallPaged": InteractionsCallPaged, + "InteractionsChatMessage": InteractionsChatMessage, + "InteractionsChatMessagePaged": InteractionsChatMessagePaged, + "InteractionsEmail": InteractionsEmail, + "InteractionsEmailPaged": InteractionsEmailPaged, + "InteractionsMeeting": InteractionsMeeting, + "InteractionsMeetingPaged": InteractionsMeetingPaged, "List": List, "ListEntry": ListEntry, "ListEntryBatchOperationResponse": ListEntryBatchOperationResponse, @@ -327,14 +468,47 @@ let typeMap: {[index: string]: any} = { "NotFoundError": NotFoundError, "NotFoundErrors": NotFoundErrors, "NotImplementedError": NotImplementedError, + "NotesAiNotetakerReplyNote": NotesAiNotetakerReplyNote, + "NotesAiNotetakerRootNote": NotesAiNotetakerRootNote, + "NotesBaseNote": NotesBaseNote, + "NotesBaseReply": NotesBaseReply, + "NotesBaseReplyParent": NotesBaseReplyParent, + "NotesBaseRootNote": NotesBaseRootNote, + "NotesCallInteraction": NotesCallInteraction, + "NotesChatMessageInteraction": NotesChatMessageInteraction, + "NotesCompaniesPreview": NotesCompaniesPreview, + "NotesContent": NotesContent, + "NotesEmailInteraction": NotesEmailInteraction, + "NotesEntitiesNote": NotesEntitiesNote, + "NotesInteraction": NotesInteractionClass, + "NotesInteractionNote": NotesInteractionNote, + "NotesMeetingInteraction": NotesMeetingInteraction, + "NotesNote": NotesNoteClass, + "NotesNotesPaged": NotesNotesPaged, + "NotesOpportunitiesPreview": NotesOpportunitiesPreview, + "NotesPermissionSettings": NotesPermissionSettings, + "NotesPersonMention": NotesPersonMention, + "NotesPersonsPreview": NotesPersonsPreview, + "NotesRepliesPaged": NotesRepliesPaged, + "NotesReply": NotesReplyClass, + "NotesUserReplyNote": NotesUserReplyNote, "Opportunity": Opportunity, "OpportunityListEntry": OpportunityListEntry, "OpportunityPaged": OpportunityPaged, "OpportunityWithFields": OpportunityWithFields, "Pagination": Pagination, + "PaginationWithTotalCount": PaginationWithTotalCount, "Person": Person, "PersonData": PersonData, + "PersonDataPaged": PersonDataPaged, + "PersonDataPreview": PersonDataPreview, "PersonListEntry": PersonListEntry, + "PersonMergeRequest": PersonMergeRequest, + "PersonMergeResponse": PersonMergeResponse, + "PersonMergeState": PersonMergeState, + "PersonMergeStatePaged": PersonMergeStatePaged, + "PersonMergeTask": PersonMergeTask, + "PersonMergeTaskPaged": PersonMergeTaskPaged, "PersonPaged": PersonPaged, "PersonReference": PersonReference, "PersonValue": PersonValue, @@ -347,6 +521,8 @@ let typeMap: {[index: string]: any} = { "RankedDropdownValue": RankedDropdownValue, "RankedDropdownValueUpdate": RankedDropdownValueUpdate, "RateLimitError": RateLimitError, + "Responses400": Responses400, + "Responses400ErrorsInner": Responses400ErrorsInnerClass, "SavedView": SavedView, "SavedViewPaged": SavedViewPaged, "ServerError": ServerError, @@ -488,13 +664,16 @@ export class ObjectSerializer { } return transformedData; } else if (type === "Date") { + if (!(data instanceof Date)) { + return data; + } if (format == "date") { let month = data.getMonth()+1 - month = month < 10 ? "0" + month.toString() : month.toString() + let monthStr = month < 10 ? "0" + month.toString() : month.toString() let day = data.getDate(); - day = day < 10 ? "0" + day.toString() : day.toString(); + let dayStr = day < 10 ? "0" + day.toString() : day.toString(); - return data.getFullYear() + "-" + month + "-" + day; + return data.getFullYear() + "-" + monthStr + "-" + dayStr; } else { return data.toISOString(); } diff --git a/src/v2/generated/models/Opportunity.ts b/src/v2/generated/models/Opportunity.ts index 711518a..09d1075 100644 --- a/src/v2/generated/models/Opportunity.ts +++ b/src/v2/generated/models/Opportunity.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/OpportunityListEntry.ts b/src/v2/generated/models/OpportunityListEntry.ts index c965854..572bb07 100644 --- a/src/v2/generated/models/OpportunityListEntry.ts +++ b/src/v2/generated/models/OpportunityListEntry.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/OpportunityPaged.ts b/src/v2/generated/models/OpportunityPaged.ts index c83d9f0..d202c94 100644 --- a/src/v2/generated/models/OpportunityPaged.ts +++ b/src/v2/generated/models/OpportunityPaged.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/OpportunityWithFields.ts b/src/v2/generated/models/OpportunityWithFields.ts index 4f18846..c4fdc83 100644 --- a/src/v2/generated/models/OpportunityWithFields.ts +++ b/src/v2/generated/models/OpportunityWithFields.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/Pagination.ts b/src/v2/generated/models/Pagination.ts index 297ec5a..e671dc0 100644 --- a/src/v2/generated/models/Pagination.ts +++ b/src/v2/generated/models/Pagination.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -31,13 +31,13 @@ export class Pagination { "name": "prevUrl", "baseName": "prevUrl", "type": "string", - "format": "url" + "format": "uri" }, { "name": "nextUrl", "baseName": "nextUrl", "type": "string", - "format": "url" + "format": "uri" } ]; static getAttributeTypeMap() { diff --git a/src/v2/generated/models/PaginationWithTotalCount.ts b/src/v2/generated/models/PaginationWithTotalCount.ts new file mode 100644 index 0000000..fc92829 --- /dev/null +++ b/src/v2/generated/models/PaginationWithTotalCount.ts @@ -0,0 +1,59 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { HttpFile } from '../http/http.ts'; + +export class PaginationWithTotalCount { + /** + * URL for the previous page + */ + 'prevUrl'?: string; + /** + * URL for the next page + */ + 'nextUrl'?: string; + /** + * The total count of the collection. Only included if requested via the totalCount query string parameter. + */ + 'totalCount'?: number; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "prevUrl", + "baseName": "prevUrl", + "type": "string", + "format": "uri" + }, + { + "name": "nextUrl", + "baseName": "nextUrl", + "type": "string", + "format": "uri" + }, + { + "name": "totalCount", + "baseName": "totalCount", + "type": "number", + "format": "int64" + } ]; + + static getAttributeTypeMap() { + return PaginationWithTotalCount.attributeTypeMap; + } + + public constructor() { + } +} diff --git a/src/v2/generated/models/Person.ts b/src/v2/generated/models/Person.ts index f21d38b..322267e 100644 --- a/src/v2/generated/models/Person.ts +++ b/src/v2/generated/models/Person.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/PersonData.ts b/src/v2/generated/models/PersonData.ts index d1dae73..27a9fc6 100644 --- a/src/v2/generated/models/PersonData.ts +++ b/src/v2/generated/models/PersonData.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/PersonDataPaged.ts b/src/v2/generated/models/PersonDataPaged.ts new file mode 100644 index 0000000..0e44706 --- /dev/null +++ b/src/v2/generated/models/PersonDataPaged.ts @@ -0,0 +1,51 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { Pagination } from '../models/Pagination.ts'; +import { PersonData } from '../models/PersonData.ts'; +import { HttpFile } from '../http/http.ts'; + +/** +* PersonDataPaged model +*/ +export class PersonDataPaged { + /** + * A page of Person results + */ + 'data': Array; + 'pagination': Pagination; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "data", + "baseName": "data", + "type": "Array", + "format": "" + }, + { + "name": "pagination", + "baseName": "pagination", + "type": "Pagination", + "format": "" + } ]; + + static getAttributeTypeMap() { + return PersonDataPaged.attributeTypeMap; + } + + public constructor() { + } +} diff --git a/src/v2/generated/models/PersonDataPreview.ts b/src/v2/generated/models/PersonDataPreview.ts new file mode 100644 index 0000000..8a310b4 --- /dev/null +++ b/src/v2/generated/models/PersonDataPreview.ts @@ -0,0 +1,50 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { PersonData } from '../models/PersonData.ts'; +import { HttpFile } from '../http/http.ts'; + +export class PersonDataPreview { + /** + * A preview of persons + */ + 'data': Array; + /** + * The total count of persons + */ + 'totalCount': number; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "data", + "baseName": "data", + "type": "Array", + "format": "" + }, + { + "name": "totalCount", + "baseName": "totalCount", + "type": "number", + "format": "int64" + } ]; + + static getAttributeTypeMap() { + return PersonDataPreview.attributeTypeMap; + } + + public constructor() { + } +} diff --git a/src/v2/generated/models/PersonListEntry.ts b/src/v2/generated/models/PersonListEntry.ts index c5fdc04..ec04e73 100644 --- a/src/v2/generated/models/PersonListEntry.ts +++ b/src/v2/generated/models/PersonListEntry.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/PersonMergeRequest.ts b/src/v2/generated/models/PersonMergeRequest.ts new file mode 100644 index 0000000..52844cb --- /dev/null +++ b/src/v2/generated/models/PersonMergeRequest.ts @@ -0,0 +1,52 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { HttpFile } from '../http/http.ts'; + +/** +* Request body for initiating a person merge +*/ +export class PersonMergeRequest { + /** + * The ID of the person profile that will be kept after the merge. All data from the duplicate person will be merged into this person. + */ + 'primaryPersonId': number; + /** + * The ID of the person profile that will be merged and then deleted. All data from this person will be transferred to the primary person. + */ + 'duplicatePersonId': number; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "primaryPersonId", + "baseName": "primaryPersonId", + "type": "number", + "format": "int64" + }, + { + "name": "duplicatePersonId", + "baseName": "duplicatePersonId", + "type": "number", + "format": "int64" + } ]; + + static getAttributeTypeMap() { + return PersonMergeRequest.attributeTypeMap; + } + + public constructor() { + } +} diff --git a/src/v2/generated/models/PersonMergeResponse.ts b/src/v2/generated/models/PersonMergeResponse.ts new file mode 100644 index 0000000..4c2bed2 --- /dev/null +++ b/src/v2/generated/models/PersonMergeResponse.ts @@ -0,0 +1,42 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { HttpFile } from '../http/http.ts'; + +/** +* Response body for initiating a person merge +*/ +export class PersonMergeResponse { + /** + * URL to check the status of the merge task + */ + 'taskUrl': string; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "taskUrl", + "baseName": "taskUrl", + "type": "string", + "format": "uri" + } ]; + + static getAttributeTypeMap() { + return PersonMergeResponse.attributeTypeMap; + } + + public constructor() { + } +} diff --git a/src/v2/generated/models/PersonMergeState.ts b/src/v2/generated/models/PersonMergeState.ts new file mode 100644 index 0000000..e05da24 --- /dev/null +++ b/src/v2/generated/models/PersonMergeState.ts @@ -0,0 +1,119 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { HttpFile } from '../http/http.ts'; + +/** +* Entity representing the state of an individual person merge +*/ +export class PersonMergeState { + /** + * The unique identifier for the merge + */ + 'id': number; + /** + * Current status of the merge + */ + 'status': PersonMergeStateStatusEnum; + /** + * Identifier for the task this merge belongs to + */ + 'taskId': string; + /** + * Timestamp when the merge started + */ + 'startedAt': Date; + /** + * ID of the primary person that other profiles were merged into + */ + 'primaryPersonId': number; + /** + * ID of the duplicate person that was merged into the primary person + */ + 'duplicatePersonId': number; + /** + * Timestamp when the merge completed (success or failure) + */ + 'completedAt': Date | null; + /** + * Error message if the merge failed + */ + 'errorMessage': string | null; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "id", + "baseName": "id", + "type": "number", + "format": "int64" + }, + { + "name": "status", + "baseName": "status", + "type": "PersonMergeStateStatusEnum", + "format": "" + }, + { + "name": "taskId", + "baseName": "taskId", + "type": "string", + "format": "uuid" + }, + { + "name": "startedAt", + "baseName": "startedAt", + "type": "Date", + "format": "date-time" + }, + { + "name": "primaryPersonId", + "baseName": "primaryPersonId", + "type": "number", + "format": "int64" + }, + { + "name": "duplicatePersonId", + "baseName": "duplicatePersonId", + "type": "number", + "format": "int64" + }, + { + "name": "completedAt", + "baseName": "completedAt", + "type": "Date", + "format": "date-time" + }, + { + "name": "errorMessage", + "baseName": "errorMessage", + "type": "string", + "format": "" + } ]; + + static getAttributeTypeMap() { + return PersonMergeState.attributeTypeMap; + } + + public constructor() { + } +} + +export enum PersonMergeStateStatusEnum { + InProgress = 'in-progress', + Success = 'success', + Failed = 'failed' +} + diff --git a/src/v2/generated/models/PersonMergeStatePaged.ts b/src/v2/generated/models/PersonMergeStatePaged.ts new file mode 100644 index 0000000..1706239 --- /dev/null +++ b/src/v2/generated/models/PersonMergeStatePaged.ts @@ -0,0 +1,51 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { Pagination } from '../models/Pagination.ts'; +import { PersonMergeState } from '../models/PersonMergeState.ts'; +import { HttpFile } from '../http/http.ts'; + +/** +* Paginated person merge states +*/ +export class PersonMergeStatePaged { + /** + * Array of person merge states + */ + 'data': Array; + 'pagination': Pagination; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "data", + "baseName": "data", + "type": "Array", + "format": "" + }, + { + "name": "pagination", + "baseName": "pagination", + "type": "Pagination", + "format": "" + } ]; + + static getAttributeTypeMap() { + return PersonMergeStatePaged.attributeTypeMap; + } + + public constructor() { + } +} diff --git a/src/v2/generated/models/PersonMergeTask.ts b/src/v2/generated/models/PersonMergeTask.ts new file mode 100644 index 0000000..a8c9cf7 --- /dev/null +++ b/src/v2/generated/models/PersonMergeTask.ts @@ -0,0 +1,67 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { CompanyMergeTaskResultsSummary } from '../models/CompanyMergeTaskResultsSummary.ts'; +import { HttpFile } from '../http/http.ts'; + +/** +* Person merge task details and status for batch operations +*/ +export class PersonMergeTask { + /** + * The unique identifier for this merge task + */ + 'id': string; + /** + * The current status of the batch operation + */ + 'status': PersonMergeTaskStatusEnum; + 'resultsSummary': CompanyMergeTaskResultsSummary; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "id", + "baseName": "id", + "type": "string", + "format": "uuid" + }, + { + "name": "status", + "baseName": "status", + "type": "PersonMergeTaskStatusEnum", + "format": "" + }, + { + "name": "resultsSummary", + "baseName": "resultsSummary", + "type": "CompanyMergeTaskResultsSummary", + "format": "" + } ]; + + static getAttributeTypeMap() { + return PersonMergeTask.attributeTypeMap; + } + + public constructor() { + } +} + +export enum PersonMergeTaskStatusEnum { + InProgress = 'in-progress', + Success = 'success', + Failed = 'failed' +} + diff --git a/src/v2/generated/models/PersonMergeTaskPaged.ts b/src/v2/generated/models/PersonMergeTaskPaged.ts new file mode 100644 index 0000000..8a0d6e2 --- /dev/null +++ b/src/v2/generated/models/PersonMergeTaskPaged.ts @@ -0,0 +1,51 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { Pagination } from '../models/Pagination.ts'; +import { PersonMergeTask } from '../models/PersonMergeTask.ts'; +import { HttpFile } from '../http/http.ts'; + +/** +* Paginated person merge tasks +*/ +export class PersonMergeTaskPaged { + /** + * Array of person merge tasks + */ + 'data': Array; + 'pagination': Pagination; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "data", + "baseName": "data", + "type": "Array", + "format": "" + }, + { + "name": "pagination", + "baseName": "pagination", + "type": "Pagination", + "format": "" + } ]; + + static getAttributeTypeMap() { + return PersonMergeTaskPaged.attributeTypeMap; + } + + public constructor() { + } +} diff --git a/src/v2/generated/models/PersonPaged.ts b/src/v2/generated/models/PersonPaged.ts index e5a3d81..18173b9 100644 --- a/src/v2/generated/models/PersonPaged.ts +++ b/src/v2/generated/models/PersonPaged.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/PersonReference.ts b/src/v2/generated/models/PersonReference.ts index d14c40f..207121d 100644 --- a/src/v2/generated/models/PersonReference.ts +++ b/src/v2/generated/models/PersonReference.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/PersonValue.ts b/src/v2/generated/models/PersonValue.ts index d265835..7c1f4c8 100644 --- a/src/v2/generated/models/PersonValue.ts +++ b/src/v2/generated/models/PersonValue.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/PersonValueUpdate.ts b/src/v2/generated/models/PersonValueUpdate.ts index bcea0b2..fffba18 100644 --- a/src/v2/generated/models/PersonValueUpdate.ts +++ b/src/v2/generated/models/PersonValueUpdate.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/PersonsValue.ts b/src/v2/generated/models/PersonsValue.ts index 74b5991..9e50552 100644 --- a/src/v2/generated/models/PersonsValue.ts +++ b/src/v2/generated/models/PersonsValue.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/PersonsValueUpdate.ts b/src/v2/generated/models/PersonsValueUpdate.ts index 2eb9e1d..524254b 100644 --- a/src/v2/generated/models/PersonsValueUpdate.ts +++ b/src/v2/generated/models/PersonsValueUpdate.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/PhoneCall.ts b/src/v2/generated/models/PhoneCall.ts index cd1d2f0..fcedfe2 100644 --- a/src/v2/generated/models/PhoneCall.ts +++ b/src/v2/generated/models/PhoneCall.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). @@ -19,7 +19,7 @@ export class PhoneCall { */ 'type': PhoneCallTypeEnum; /** - * The phon_call\'s unique identifier + * The phone call\'s unique identifier */ 'id': number; /** diff --git a/src/v2/generated/models/RankedDropdown.ts b/src/v2/generated/models/RankedDropdown.ts index 8663744..ab46002 100644 --- a/src/v2/generated/models/RankedDropdown.ts +++ b/src/v2/generated/models/RankedDropdown.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/RankedDropdownReference.ts b/src/v2/generated/models/RankedDropdownReference.ts index e4527d0..98604d0 100644 --- a/src/v2/generated/models/RankedDropdownReference.ts +++ b/src/v2/generated/models/RankedDropdownReference.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/RankedDropdownValue.ts b/src/v2/generated/models/RankedDropdownValue.ts index db61901..36de35f 100644 --- a/src/v2/generated/models/RankedDropdownValue.ts +++ b/src/v2/generated/models/RankedDropdownValue.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/RankedDropdownValueUpdate.ts b/src/v2/generated/models/RankedDropdownValueUpdate.ts index 9d37942..c18173f 100644 --- a/src/v2/generated/models/RankedDropdownValueUpdate.ts +++ b/src/v2/generated/models/RankedDropdownValueUpdate.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/RateLimitError.ts b/src/v2/generated/models/RateLimitError.ts index db81522..7294fe2 100644 --- a/src/v2/generated/models/RateLimitError.ts +++ b/src/v2/generated/models/RateLimitError.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/Responses400.ts b/src/v2/generated/models/Responses400.ts new file mode 100644 index 0000000..292c122 --- /dev/null +++ b/src/v2/generated/models/Responses400.ts @@ -0,0 +1,37 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { Responses400ErrorsInner } from '../models/Responses400ErrorsInner.ts'; +import { HttpFile } from '../http/http.ts'; + +export class Responses400 { + 'errors': Array; + + static readonly discriminator: string | undefined = undefined; + + static readonly mapping: {[index: string]: string} | undefined = undefined; + + static readonly attributeTypeMap: Array<{name: string, baseName: string, type: string, format: string}> = [ + { + "name": "errors", + "baseName": "errors", + "type": "Array", + "format": "" + } ]; + + static getAttributeTypeMap() { + return Responses400.attributeTypeMap; + } + + public constructor() { + } +} diff --git a/src/v2/generated/models/Responses400ErrorsInner.ts b/src/v2/generated/models/Responses400ErrorsInner.ts new file mode 100644 index 0000000..4033841 --- /dev/null +++ b/src/v2/generated/models/Responses400ErrorsInner.ts @@ -0,0 +1,36 @@ +/** + * Affinity API v2 + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * + * OpenAPI spec version: + * Contact: support@affinity.co + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + +import { BadRequestError } from '../models/BadRequestError.ts'; +import { ValidationError } from '../models/ValidationError.ts'; +import { HttpFile } from '../http/http.ts'; + +/** + * @type Responses400ErrorsInner + * Type + * @export + */ +export type Responses400ErrorsInner = BadRequestError | ValidationError; + +/** +* @type Responses400ErrorsInnerClass +* @export +*/ +export class Responses400ErrorsInnerClass { + static readonly discriminator: string | undefined = "code"; + + static readonly mapping: {[index: string]: string} | undefined = { + "bad-request": "BadRequestError", + "validation": "ValidationError", + }; +} + diff --git a/src/v2/generated/models/SavedView.ts b/src/v2/generated/models/SavedView.ts index 566d2b7..7cf07e6 100644 --- a/src/v2/generated/models/SavedView.ts +++ b/src/v2/generated/models/SavedView.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/SavedViewPaged.ts b/src/v2/generated/models/SavedViewPaged.ts index 0a13e75..1c4f9a0 100644 --- a/src/v2/generated/models/SavedViewPaged.ts +++ b/src/v2/generated/models/SavedViewPaged.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/ServerError.ts b/src/v2/generated/models/ServerError.ts index 6f3e79e..613d65e 100644 --- a/src/v2/generated/models/ServerError.ts +++ b/src/v2/generated/models/ServerError.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/Tenant.ts b/src/v2/generated/models/Tenant.ts index 7568080..1635e81 100644 --- a/src/v2/generated/models/Tenant.ts +++ b/src/v2/generated/models/Tenant.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/TextValue.ts b/src/v2/generated/models/TextValue.ts index e8be0e0..e1428c0 100644 --- a/src/v2/generated/models/TextValue.ts +++ b/src/v2/generated/models/TextValue.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/TextsValue.ts b/src/v2/generated/models/TextsValue.ts index 2cf1388..f9eea07 100644 --- a/src/v2/generated/models/TextsValue.ts +++ b/src/v2/generated/models/TextsValue.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/UnprocessableEntityError.ts b/src/v2/generated/models/UnprocessableEntityError.ts index 1ad3c23..9b2ec7f 100644 --- a/src/v2/generated/models/UnprocessableEntityError.ts +++ b/src/v2/generated/models/UnprocessableEntityError.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/UnsupportedMediaTypeError.ts b/src/v2/generated/models/UnsupportedMediaTypeError.ts index 1ae3c45..f74c35c 100644 --- a/src/v2/generated/models/UnsupportedMediaTypeError.ts +++ b/src/v2/generated/models/UnsupportedMediaTypeError.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/User.ts b/src/v2/generated/models/User.ts index 4b325e2..dcdbcdc 100644 --- a/src/v2/generated/models/User.ts +++ b/src/v2/generated/models/User.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/ValidationError.ts b/src/v2/generated/models/ValidationError.ts index 2cd0f68..8a6c73e 100644 --- a/src/v2/generated/models/ValidationError.ts +++ b/src/v2/generated/models/ValidationError.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/WhoAmI.ts b/src/v2/generated/models/WhoAmI.ts index 67d0969..4574358 100644 --- a/src/v2/generated/models/WhoAmI.ts +++ b/src/v2/generated/models/WhoAmI.ts @@ -1,8 +1,8 @@ /** * Affinity API v2 - * # Introduction Welcome to Affinity API v2! This API provides a RESTful interface for building internal apps, automated workflows, and other integrations on top of the core data models in Affinity, and for connecting Affinity to the rest of your tech and data stack. Please note that this new version of the API is not at feature parity with [Affinity API v1](https://api-docs.affinity.co/). We will add to this new version to cover more of v1\'s functionality over time. **This API version is also only available on select Affinity 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. ## Using These Docs 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. Please note that 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. You will need the \"Generate an API key\" role-based permission controlled by your Affinity admin to be able to do this. 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. Currently, we support one API key per user in your Affinity account. 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. Provide your API key as your bearer authentication token to start making calls to Affinity API v2. ## Permissions ### Overall requirements You must have the \"Generate an API key\" permission to be able to work with the Affinity API. Most users in most Affinity accounts with API access 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 also require endpoint-specific permissions that map to permissions in-product. These permissions, along with the \"Generate an API key\" permission, are managed by your Affinity admin in the Settings page: | API v2 Endpoint | Required Permission | | ---------------------------------------------------------- | ------------------------------------ | | GET `/v2/companies` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}` | \"Export All Organizations directory\" | | GET `/v2/companies/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/persons` | \"Export All People directory\" | | GET `/v2/persons/{id}` | \"Export All People directory\" | | GET `/v2/persons/{id}/list-entries` | \"Export data from Lists\" | | GET `/v2/opportunities` | \"Export data from Lists\" | | GET `/v2/opportunities/{id}` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/list-entries` | \"Export data from Lists\" | | GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | \"Export data from Lists\" | ## 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 up 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. ## Error Codes Here is a list of the error codes this API will generally return if something goes wrong (see endpoint documentation for endpoint-specific error information): | 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. | # Data Model ## The Basics - The three top-level objects in Affinity are **Persons, Companies, and Opportunities**. (Please 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 lot of the work of Affinity happens within 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. - Do note that a given entity can be added to a List more than once, i.e., it can have multiple List Entries on the same List. 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 and field data also show up within Affinity profile pages, extensions, and integrations. - Some Fields are scoped to a single List — These are **list-specific fields**, and in the API, their data can only be accessed through the List Entry resource. \"Global\" data from other Fields can be accessed both through the Person/Company/Opportunity resource and the List Entry resource. ## Working with Field Data ### Field Types and IDs There are a few 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 [here](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`\\* | \\*Please 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) ## A Note on 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## February 28th, 2024 - 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, 2024 - Document `X-Ratelimit` headers in the schema for all endpoints. ## January 15th, 2024 - 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. + * # 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** (this is an important difference from Affinity API v1\'s use of basic authentication). To generate an API key, navigate to the Settings page in the Affinity web app. 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. We support one API key per user in your Affinity account. 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. ## 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. | ## 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. # User Guides ## A Tour of Our GET Endpoints | Desired Data | Relevant Endpoints | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Company/Person/Opportunity rows from a List | Grab the List’s ID from its URL in the Affinity web app, then hit GET `/v2/lists/{listId}/list-entries` | Data returned will be restricted to the rows on the requested List | | Company/Person/Opportunity rows from a Saved View | In the Affinity web app, navigate to a List and [create a Saved View](https://support.affinity.co/hc/en-us/articles/115001508572-How-to-leverage-saved-views-within-a-list) with the desired field data and filters on it. Grab the List and Saved View IDs from the web app URL, then hit GET `/v2/lists/{listId}/saved-views/{viewId}/list-entries` | Data returned will be restricted to the rows and columns on the requested Saved View | | Full rolodex of Companies or Persons in Affinity | GET `/v2/companies`, GET `/v2/persons` | Data from list-specific Fields will not be returned | | All the rows for a given Company or Person across all Lists | GET `/v2/companies/{id}/list-entries`, GET `/v2/persons/{id}/list-entries` | | | Metadata on Fields, including Field IDs | GET `/v2/companies/fields`, GET `/v2/persons/fields`, GET `/v2/lists/{listId}/fields` | Metadata on list-specific Fields will only be returned by GET `/v2/lists/{listId}/fields` | | Metadata on Lists or Saved Views | GET `/v2/lists`, GET `/v2/lists/{listId}/saved-views` | | | Opportunity data | GET `/v2/opportunities` will only return Opportunity names and List IDs. For comprehensive Opportunity data, hit GET `/v2/lists/{listId}/list-entries` for an Opportunity List | | Tip: The ID for a List, Saved View, Person, Company, or Opportunity can always be found in its Affinity web app URL. # Changelog ## 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 | ## 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)](#section/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](#section/Data-Model/Working-with-Field-Data) section of these docs for more information. * - * OpenAPI spec version: 2024-01-01 + * OpenAPI spec version: * Contact: support@affinity.co * * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). diff --git a/src/v2/generated/models/all.ts b/src/v2/generated/models/all.ts index 8403648..9ab7c4a 100644 --- a/src/v2/generated/models/all.ts +++ b/src/v2/generated/models/all.ts @@ -1,4 +1,5 @@ export * from '../models/Attendee.ts' +export * from '../models/AttendeesPreview.ts' export * from '../models/AuthenticationError.ts' export * from '../models/AuthorizationError.ts' export * from '../models/AuthorizationErrors.ts' @@ -8,7 +9,15 @@ export * from '../models/CompaniesValue.ts' export * from '../models/CompaniesValueUpdate.ts' export * from '../models/Company.ts' export * from '../models/CompanyData.ts' +export * from '../models/CompanyDataPaged.ts' export * from '../models/CompanyListEntry.ts' +export * from '../models/CompanyMergeRequest.ts' +export * from '../models/CompanyMergeResponse.ts' +export * from '../models/CompanyMergeState.ts' +export * from '../models/CompanyMergeStatePaged.ts' +export * from '../models/CompanyMergeTask.ts' +export * from '../models/CompanyMergeTaskPaged.ts' +export * from '../models/CompanyMergeTaskResultsSummary.ts' export * from '../models/CompanyPaged.ts' export * from '../models/CompanyReference.ts' export * from '../models/CompanyValue.ts' @@ -35,10 +44,16 @@ export * from '../models/FloatsValue.ts' export * from '../models/FormulaNumber.ts' export * from '../models/FormulaValue.ts' export * from '../models/Grant.ts' -export * from '../models/InlineObject.ts' -export * from '../models/InlineObjectErrorsInner.ts' export * from '../models/Interaction.ts' export * from '../models/InteractionValue.ts' +export * from '../models/InteractionsCall.ts' +export * from '../models/InteractionsCallPaged.ts' +export * from '../models/InteractionsChatMessage.ts' +export * from '../models/InteractionsChatMessagePaged.ts' +export * from '../models/InteractionsEmail.ts' +export * from '../models/InteractionsEmailPaged.ts' +export * from '../models/InteractionsMeeting.ts' +export * from '../models/InteractionsMeetingPaged.ts' export * from '../models/List.ts' export * from '../models/ListEntry.ts' export * from '../models/ListEntryBatchOperationResponse.ts' @@ -61,14 +76,47 @@ export * from '../models/NotAcceptableError.ts' export * from '../models/NotFoundError.ts' export * from '../models/NotFoundErrors.ts' export * from '../models/NotImplementedError.ts' +export * from '../models/NotesAiNotetakerReplyNote.ts' +export * from '../models/NotesAiNotetakerRootNote.ts' +export * from '../models/NotesBaseNote.ts' +export * from '../models/NotesBaseReply.ts' +export * from '../models/NotesBaseReplyParent.ts' +export * from '../models/NotesBaseRootNote.ts' +export * from '../models/NotesCallInteraction.ts' +export * from '../models/NotesChatMessageInteraction.ts' +export * from '../models/NotesCompaniesPreview.ts' +export * from '../models/NotesContent.ts' +export * from '../models/NotesEmailInteraction.ts' +export * from '../models/NotesEntitiesNote.ts' +export * from '../models/NotesInteraction.ts' +export * from '../models/NotesInteractionNote.ts' +export * from '../models/NotesMeetingInteraction.ts' +export * from '../models/NotesNote.ts' +export * from '../models/NotesNotesPaged.ts' +export * from '../models/NotesOpportunitiesPreview.ts' +export * from '../models/NotesPermissionSettings.ts' +export * from '../models/NotesPersonMention.ts' +export * from '../models/NotesPersonsPreview.ts' +export * from '../models/NotesRepliesPaged.ts' +export * from '../models/NotesReply.ts' +export * from '../models/NotesUserReplyNote.ts' export * from '../models/Opportunity.ts' export * from '../models/OpportunityListEntry.ts' export * from '../models/OpportunityPaged.ts' export * from '../models/OpportunityWithFields.ts' export * from '../models/Pagination.ts' +export * from '../models/PaginationWithTotalCount.ts' export * from '../models/Person.ts' export * from '../models/PersonData.ts' +export * from '../models/PersonDataPaged.ts' +export * from '../models/PersonDataPreview.ts' export * from '../models/PersonListEntry.ts' +export * from '../models/PersonMergeRequest.ts' +export * from '../models/PersonMergeResponse.ts' +export * from '../models/PersonMergeState.ts' +export * from '../models/PersonMergeStatePaged.ts' +export * from '../models/PersonMergeTask.ts' +export * from '../models/PersonMergeTaskPaged.ts' export * from '../models/PersonPaged.ts' export * from '../models/PersonReference.ts' export * from '../models/PersonValue.ts' @@ -81,6 +129,8 @@ export * from '../models/RankedDropdownReference.ts' export * from '../models/RankedDropdownValue.ts' export * from '../models/RankedDropdownValueUpdate.ts' export * from '../models/RateLimitError.ts' +export * from '../models/Responses400.ts' +export * from '../models/Responses400ErrorsInner.ts' export * from '../models/SavedView.ts' export * from '../models/SavedViewPaged.ts' export * from '../models/ServerError.ts' diff --git a/src/v2/generated/types/ObjectParamAPI.ts b/src/v2/generated/types/ObjectParamAPI.ts index fd4094d..26c2eab 100644 --- a/src/v2/generated/types/ObjectParamAPI.ts +++ b/src/v2/generated/types/ObjectParamAPI.ts @@ -3,6 +3,7 @@ import { Configuration, ConfigurationOptions } from '../configuration.ts' import type { Middleware } from '../middleware.ts'; import { Attendee } from '../models/Attendee.ts'; +import { AttendeesPreview } from '../models/AttendeesPreview.ts'; import { AuthenticationError } from '../models/AuthenticationError.ts'; import { AuthorizationError } from '../models/AuthorizationError.ts'; import { AuthorizationErrors } from '../models/AuthorizationErrors.ts'; @@ -12,7 +13,15 @@ import { CompaniesValue } from '../models/CompaniesValue.ts'; import { CompaniesValueUpdate } from '../models/CompaniesValueUpdate.ts'; import { Company } from '../models/Company.ts'; import { CompanyData } from '../models/CompanyData.ts'; +import { CompanyDataPaged } from '../models/CompanyDataPaged.ts'; import { CompanyListEntry } from '../models/CompanyListEntry.ts'; +import { CompanyMergeRequest } from '../models/CompanyMergeRequest.ts'; +import { CompanyMergeResponse } from '../models/CompanyMergeResponse.ts'; +import { CompanyMergeState } from '../models/CompanyMergeState.ts'; +import { CompanyMergeStatePaged } from '../models/CompanyMergeStatePaged.ts'; +import { CompanyMergeTask } from '../models/CompanyMergeTask.ts'; +import { CompanyMergeTaskPaged } from '../models/CompanyMergeTaskPaged.ts'; +import { CompanyMergeTaskResultsSummary } from '../models/CompanyMergeTaskResultsSummary.ts'; import { CompanyPaged } from '../models/CompanyPaged.ts'; import { CompanyReference } from '../models/CompanyReference.ts'; import { CompanyValue } from '../models/CompanyValue.ts'; @@ -39,10 +48,16 @@ import { FloatsValue } from '../models/FloatsValue.ts'; import { FormulaNumber } from '../models/FormulaNumber.ts'; import { FormulaValue } from '../models/FormulaValue.ts'; import { Grant } from '../models/Grant.ts'; -import { InlineObject } from '../models/InlineObject.ts'; -import { InlineObjectErrorsInner } from '../models/InlineObjectErrorsInner.ts'; import { Interaction } from '../models/Interaction.ts'; import { InteractionValue } from '../models/InteractionValue.ts'; +import { InteractionsCall } from '../models/InteractionsCall.ts'; +import { InteractionsCallPaged } from '../models/InteractionsCallPaged.ts'; +import { InteractionsChatMessage } from '../models/InteractionsChatMessage.ts'; +import { InteractionsChatMessagePaged } from '../models/InteractionsChatMessagePaged.ts'; +import { InteractionsEmail } from '../models/InteractionsEmail.ts'; +import { InteractionsEmailPaged } from '../models/InteractionsEmailPaged.ts'; +import { InteractionsMeeting } from '../models/InteractionsMeeting.ts'; +import { InteractionsMeetingPaged } from '../models/InteractionsMeetingPaged.ts'; import { List } from '../models/List.ts'; import { ListEntry } from '../models/ListEntry.ts'; import { ListEntryBatchOperationResponse } from '../models/ListEntryBatchOperationResponse.ts'; @@ -65,14 +80,47 @@ import { NotAcceptableError } from '../models/NotAcceptableError.ts'; import { NotFoundError } from '../models/NotFoundError.ts'; import { NotFoundErrors } from '../models/NotFoundErrors.ts'; import { NotImplementedError } from '../models/NotImplementedError.ts'; +import { NotesAiNotetakerReplyNote } from '../models/NotesAiNotetakerReplyNote.ts'; +import { NotesAiNotetakerRootNote } from '../models/NotesAiNotetakerRootNote.ts'; +import { NotesBaseNote } from '../models/NotesBaseNote.ts'; +import { NotesBaseReply } from '../models/NotesBaseReply.ts'; +import { NotesBaseReplyParent } from '../models/NotesBaseReplyParent.ts'; +import { NotesBaseRootNote } from '../models/NotesBaseRootNote.ts'; +import { NotesCallInteraction } from '../models/NotesCallInteraction.ts'; +import { NotesChatMessageInteraction } from '../models/NotesChatMessageInteraction.ts'; +import { NotesCompaniesPreview } from '../models/NotesCompaniesPreview.ts'; +import { NotesContent } from '../models/NotesContent.ts'; +import { NotesEmailInteraction } from '../models/NotesEmailInteraction.ts'; +import { NotesEntitiesNote } from '../models/NotesEntitiesNote.ts'; +import { NotesInteraction } from '../models/NotesInteraction.ts'; +import { NotesInteractionNote } from '../models/NotesInteractionNote.ts'; +import { NotesMeetingInteraction } from '../models/NotesMeetingInteraction.ts'; +import { NotesNote } from '../models/NotesNote.ts'; +import { NotesNotesPaged } from '../models/NotesNotesPaged.ts'; +import { NotesOpportunitiesPreview } from '../models/NotesOpportunitiesPreview.ts'; +import { NotesPermissionSettings } from '../models/NotesPermissionSettings.ts'; +import { NotesPersonMention } from '../models/NotesPersonMention.ts'; +import { NotesPersonsPreview } from '../models/NotesPersonsPreview.ts'; +import { NotesRepliesPaged } from '../models/NotesRepliesPaged.ts'; +import { NotesReply } from '../models/NotesReply.ts'; +import { NotesUserReplyNote } from '../models/NotesUserReplyNote.ts'; import { Opportunity } from '../models/Opportunity.ts'; import { OpportunityListEntry } from '../models/OpportunityListEntry.ts'; import { OpportunityPaged } from '../models/OpportunityPaged.ts'; import { OpportunityWithFields } from '../models/OpportunityWithFields.ts'; import { Pagination } from '../models/Pagination.ts'; +import { PaginationWithTotalCount } from '../models/PaginationWithTotalCount.ts'; import { Person } from '../models/Person.ts'; import { PersonData } from '../models/PersonData.ts'; +import { PersonDataPaged } from '../models/PersonDataPaged.ts'; +import { PersonDataPreview } from '../models/PersonDataPreview.ts'; import { PersonListEntry } from '../models/PersonListEntry.ts'; +import { PersonMergeRequest } from '../models/PersonMergeRequest.ts'; +import { PersonMergeResponse } from '../models/PersonMergeResponse.ts'; +import { PersonMergeState } from '../models/PersonMergeState.ts'; +import { PersonMergeStatePaged } from '../models/PersonMergeStatePaged.ts'; +import { PersonMergeTask } from '../models/PersonMergeTask.ts'; +import { PersonMergeTaskPaged } from '../models/PersonMergeTaskPaged.ts'; import { PersonPaged } from '../models/PersonPaged.ts'; import { PersonReference } from '../models/PersonReference.ts'; import { PersonValue } from '../models/PersonValue.ts'; @@ -85,6 +133,8 @@ import { RankedDropdownReference } from '../models/RankedDropdownReference.ts'; import { RankedDropdownValue } from '../models/RankedDropdownValue.ts'; import { RankedDropdownValueUpdate } from '../models/RankedDropdownValueUpdate.ts'; import { RateLimitError } from '../models/RateLimitError.ts'; +import { Responses400 } from '../models/Responses400.ts'; +import { Responses400ErrorsInner } from '../models/Responses400ErrorsInner.ts'; import { SavedView } from '../models/SavedView.ts'; import { SavedViewPaged } from '../models/SavedViewPaged.ts'; import { ServerError } from '../models/ServerError.ts'; @@ -100,7 +150,7 @@ import { WhoAmI } from '../models/WhoAmI.ts'; import { ObservableAuthApi } from "./ObservableAPI.ts"; import { AuthApiRequestFactory, AuthApiResponseProcessor} from "../apis/AuthApi.ts"; -export interface AuthApiGetV2AuthWhoamiRequest { +export interface AuthApiV2AuthWhoamiGETRequest { } export class ObjectAuthApi { @@ -111,34 +161,34 @@ export class ObjectAuthApi { } /** - * Returns metadata about the current user. + * Returns information about the authenticated user, their current organization, and API key permissions. Use this endpoint to verify your authentication and understand your available API access levels. * Get current user * @param param the request object */ - public getV2AuthWhoamiWithHttpInfo(param: AuthApiGetV2AuthWhoamiRequest = {}, options?: ConfigurationOptions): Promise> { - return this.api.getV2AuthWhoamiWithHttpInfo( options).toPromise(); + public v2AuthWhoamiGETWithHttpInfo(param: AuthApiV2AuthWhoamiGETRequest = {}, options?: ConfigurationOptions): Promise> { + return this.api.v2AuthWhoamiGETWithHttpInfo( options).toPromise(); } /** - * Returns metadata about the current user. + * Returns information about the authenticated user, their current organization, and API key permissions. Use this endpoint to verify your authentication and understand your available API access levels. * Get current user * @param param the request object */ - public getV2AuthWhoami(param: AuthApiGetV2AuthWhoamiRequest = {}, options?: ConfigurationOptions): Promise { - return this.api.getV2AuthWhoami( options).toPromise(); + public v2AuthWhoamiGET(param: AuthApiV2AuthWhoamiGETRequest = {}, options?: ConfigurationOptions): Promise { + return this.api.v2AuthWhoamiGET( options).toPromise(); } } -import { ObservableCompaniesApi } from "./ObservableAPI.ts"; -import { CompaniesApiRequestFactory, CompaniesApiResponseProcessor} from "../apis/CompaniesApi.ts"; +import { ObservableCallsApi } from "./ObservableAPI.ts"; +import { CallsApiRequestFactory, CallsApiResponseProcessor} from "../apis/CallsApi.ts"; -export interface CompaniesApiGetV2CompaniesRequest { +export interface CallsApiV2CallsGETRequest { /** * Cursor for the next or previous page * Defaults to: undefined * @type string - * @memberof CompaniesApigetV2Companies + * @memberof CallsApiv2CallsGET */ cursor?: string /** @@ -147,38 +197,54 @@ export interface CompaniesApiGetV2CompaniesRequest { * Maximum: 100 * Defaults to: 100 * @type number - * @memberof CompaniesApigetV2Companies + * @memberof CallsApiv2CallsGET */ limit?: number /** - * Company IDs + * Filter options * Defaults to: undefined - * @type Array<number> - * @memberof CompaniesApigetV2Companies + * @type string + * @memberof CallsApiv2CallsGET */ - ids?: Array + filter?: string +} + +export class ObjectCallsApi { + private api: ObservableCallsApi + + public constructor(configuration: Configuration, requestFactory?: CallsApiRequestFactory, responseProcessor?: CallsApiResponseProcessor) { + this.api = new ObservableCallsApi(configuration, requestFactory, responseProcessor); + } + /** - * Field IDs for which to return field data - * Defaults to: undefined - * @type Array<string> - * @memberof CompaniesApigetV2Companies + * Paginate through all calls in Affinity. Returns basic information about the call interaction and its participants. Will only return calls that the current authenticated user has permission to see. You can filter calls using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|----------------------------------| | `id` | Unique identifier for Calls | `int64` | `=` | `id=1` | | `startTime` | Start time of when the Call was held | `datetime` | `>`, `<`, `>=`, `<=` | `sentAt>2025-01-01T01:00:00Z` | | `createdAt` | When the Call was created in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-01-01T01:00:00Z` | | `updatedAt` | When the Call was updated in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-01-01T01:00:00Z`| + * Get metadata on all Calls + * @param param the request object */ - fieldIds?: Array + public v2CallsGETWithHttpInfo(param: CallsApiV2CallsGETRequest = {}, options?: ConfigurationOptions): Promise> { + return this.api.v2CallsGETWithHttpInfo(param.cursor, param.limit, param.filter, options).toPromise(); + } + /** - * Field Types for which to return field data - * Defaults to: undefined - * @type Array<'enriched' | 'global' | 'relationship-intelligence'> - * @memberof CompaniesApigetV2Companies + * Paginate through all calls in Affinity. Returns basic information about the call interaction and its participants. Will only return calls that the current authenticated user has permission to see. You can filter calls using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|----------------------------------| | `id` | Unique identifier for Calls | `int64` | `=` | `id=1` | | `startTime` | Start time of when the Call was held | `datetime` | `>`, `<`, `>=`, `<=` | `sentAt>2025-01-01T01:00:00Z` | | `createdAt` | When the Call was created in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-01-01T01:00:00Z` | | `updatedAt` | When the Call was updated in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-01-01T01:00:00Z`| + * Get metadata on all Calls + * @param param the request object */ - fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'> + public v2CallsGET(param: CallsApiV2CallsGETRequest = {}, options?: ConfigurationOptions): Promise { + return this.api.v2CallsGET(param.cursor, param.limit, param.filter, options).toPromise(); + } + } -export interface CompaniesApiGetV2CompaniesFieldsRequest { +import { ObservableChatMessagesApi } from "./ObservableAPI.ts"; +import { ChatMessagesApiRequestFactory, ChatMessagesApiResponseProcessor} from "../apis/ChatMessagesApi.ts"; + +export interface ChatMessagesApiV2ChatMessagesGETRequest { /** * Cursor for the next or previous page * Defaults to: undefined * @type string - * @memberof CompaniesApigetV2CompaniesFields + * @memberof ChatMessagesApiv2ChatMessagesGET */ cursor?: string /** @@ -187,52 +253,89 @@ export interface CompaniesApiGetV2CompaniesFieldsRequest { * Maximum: 100 * Defaults to: 100 * @type number - * @memberof CompaniesApigetV2CompaniesFields + * @memberof ChatMessagesApiv2ChatMessagesGET */ limit?: number + /** + * Filter options + * Defaults to: undefined + * @type string + * @memberof ChatMessagesApiv2ChatMessagesGET + */ + filter?: string +} + +export class ObjectChatMessagesApi { + private api: ObservableChatMessagesApi + + public constructor(configuration: Configuration, requestFactory?: ChatMessagesApiRequestFactory, responseProcessor?: ChatMessagesApiResponseProcessor) { + this.api = new ObservableChatMessagesApi(configuration, requestFactory, responseProcessor); + } + + /** + * Paginate through all chat messages in Affinity. Returns basic information about the chat message interaction and its participants. Will only return chat messages that the current authenticated user has permission to see. You can filter chat messages using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|----------------------------------| | `id` | Unique identifier for Chat Messages | `int64` | `=` | `id=1` | | `sentAt` | When the Chat Message was sent at | `datetime` | `>`, `<`, `>=`, `<=` | `sentAt>2025-01-01T01:00:00Z` | | `createdAt` | When the Chat Message was created in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-01-01T01:00:00Z` | | `updatedAt` | When the Chat Message was updated in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-01-01T01:00:00Z`| + * Get metadata on all Chat Messages + * @param param the request object + */ + public v2ChatMessagesGETWithHttpInfo(param: ChatMessagesApiV2ChatMessagesGETRequest = {}, options?: ConfigurationOptions): Promise> { + return this.api.v2ChatMessagesGETWithHttpInfo(param.cursor, param.limit, param.filter, options).toPromise(); + } + + /** + * Paginate through all chat messages in Affinity. Returns basic information about the chat message interaction and its participants. Will only return chat messages that the current authenticated user has permission to see. You can filter chat messages using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|----------------------------------| | `id` | Unique identifier for Chat Messages | `int64` | `=` | `id=1` | | `sentAt` | When the Chat Message was sent at | `datetime` | `>`, `<`, `>=`, `<=` | `sentAt>2025-01-01T01:00:00Z` | | `createdAt` | When the Chat Message was created in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-01-01T01:00:00Z` | | `updatedAt` | When the Chat Message was updated in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-01-01T01:00:00Z`| + * Get metadata on all Chat Messages + * @param param the request object + */ + public v2ChatMessagesGET(param: ChatMessagesApiV2ChatMessagesGETRequest = {}, options?: ConfigurationOptions): Promise { + return this.api.v2ChatMessagesGET(param.cursor, param.limit, param.filter, options).toPromise(); + } + } -export interface CompaniesApiGetV2CompaniesIdRequest { +import { ObservableCompaniesApi } from "./ObservableAPI.ts"; +import { CompaniesApiRequestFactory, CompaniesApiResponseProcessor} from "../apis/CompaniesApi.ts"; + +export interface CompaniesApiV2CompaniesCompanyIdGETRequest { /** * Company ID * Minimum: 1 - * Maximum: -9223372036854775616 + * Maximum: 9223372036854776000 * Defaults to: undefined * @type number - * @memberof CompaniesApigetV2CompaniesId + * @memberof CompaniesApiv2CompaniesCompanyIdGET */ - id: number + companyId: number /** * Field IDs for which to return field data * Defaults to: undefined * @type Array<string> - * @memberof CompaniesApigetV2CompaniesId + * @memberof CompaniesApiv2CompaniesCompanyIdGET */ fieldIds?: Array /** * Field Types for which to return field data * Defaults to: undefined * @type Array<'enriched' | 'global' | 'relationship-intelligence'> - * @memberof CompaniesApigetV2CompaniesId + * @memberof CompaniesApiv2CompaniesCompanyIdGET */ fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'> } -export interface CompaniesApiGetV2CompaniesIdListEntriesRequest { +export interface CompaniesApiV2CompaniesCompanyIdListEntriesGETRequest { /** * Company ID * Minimum: 1 - * Maximum: -9223372036854775616 + * Maximum: 9223372036854776000 * Defaults to: undefined * @type number - * @memberof CompaniesApigetV2CompaniesIdListEntries + * @memberof CompaniesApiv2CompaniesCompanyIdListEntriesGET */ - id: number + companyId: number /** * Cursor for the next or previous page * Defaults to: undefined * @type string - * @memberof CompaniesApigetV2CompaniesIdListEntries + * @memberof CompaniesApiv2CompaniesCompanyIdListEntriesGET */ cursor?: string /** @@ -241,26 +344,106 @@ export interface CompaniesApiGetV2CompaniesIdListEntriesRequest { * Maximum: 100 * Defaults to: 100 * @type number - * @memberof CompaniesApigetV2CompaniesIdListEntries + * @memberof CompaniesApiv2CompaniesCompanyIdListEntriesGET */ limit?: number } -export interface CompaniesApiGetV2CompaniesIdListsRequest { +export interface CompaniesApiV2CompaniesCompanyIdListsGETRequest { /** * Company ID * Minimum: 1 - * Maximum: -9223372036854775616 + * Maximum: 9223372036854776000 + * Defaults to: undefined + * @type number + * @memberof CompaniesApiv2CompaniesCompanyIdListsGET + */ + companyId: number + /** + * Cursor for the next or previous page + * Defaults to: undefined + * @type string + * @memberof CompaniesApiv2CompaniesCompanyIdListsGET + */ + cursor?: string + /** + * Number of items to include in the page + * Minimum: 1 + * Maximum: 100 + * Defaults to: 100 + * @type number + * @memberof CompaniesApiv2CompaniesCompanyIdListsGET + */ + limit?: number +} + +export interface CompaniesApiV2CompaniesCompanyIdNotesGETRequest { + /** + * Company\'s ID + * Minimum: 1 + * Maximum: 9223372036854776000 + * Defaults to: undefined + * @type number + * @memberof CompaniesApiv2CompaniesCompanyIdNotesGET + */ + companyId: number + /** + * Filter options + * Defaults to: undefined + * @type string + * @memberof CompaniesApiv2CompaniesCompanyIdNotesGET + */ + filter?: string + /** + * Cursor for the next or previous page + * Defaults to: undefined + * @type string + * @memberof CompaniesApiv2CompaniesCompanyIdNotesGET + */ + cursor?: string + /** + * Number of items to include in the page + * Minimum: 0 + * Maximum: 100 + * Defaults to: 20 + * @type number + * @memberof CompaniesApiv2CompaniesCompanyIdNotesGET + */ + limit?: number + /** + * Include total count of the collection in the pagination response + * Defaults to: false + * @type boolean + * @memberof CompaniesApiv2CompaniesCompanyIdNotesGET + */ + totalCount?: boolean +} + +export interface CompaniesApiV2CompaniesFieldsGETRequest { + /** + * Cursor for the next or previous page * Defaults to: undefined + * @type string + * @memberof CompaniesApiv2CompaniesFieldsGET + */ + cursor?: string + /** + * Number of items to include in the page + * Minimum: 1 + * Maximum: 100 + * Defaults to: 100 * @type number - * @memberof CompaniesApigetV2CompaniesIdLists + * @memberof CompaniesApiv2CompaniesFieldsGET */ - id: number + limit?: number +} + +export interface CompaniesApiV2CompaniesGETRequest { /** * Cursor for the next or previous page * Defaults to: undefined * @type string - * @memberof CompaniesApigetV2CompaniesIdLists + * @memberof CompaniesApiv2CompaniesGET */ cursor?: string /** @@ -269,9 +452,30 @@ export interface CompaniesApiGetV2CompaniesIdListsRequest { * Maximum: 100 * Defaults to: 100 * @type number - * @memberof CompaniesApigetV2CompaniesIdLists + * @memberof CompaniesApiv2CompaniesGET */ limit?: number + /** + * Company IDs + * Defaults to: undefined + * @type Array<number> + * @memberof CompaniesApiv2CompaniesGET + */ + ids?: Array + /** + * Field IDs for which to return field data + * Defaults to: undefined + * @type Array<string> + * @memberof CompaniesApiv2CompaniesGET + */ + fieldIds?: Array + /** + * Field Types for which to return field data + * Defaults to: undefined + * @type Array<'enriched' | 'global' | 'relationship-intelligence'> + * @memberof CompaniesApiv2CompaniesGET + */ + fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'> } export class ObjectCompaniesApi { @@ -282,115 +486,124 @@ export class ObjectCompaniesApi { } /** - * Paginate through Companies in Affinity. Returns basic information and non-list-specific field data on each Company. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/companies/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Companies will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All Organizations directory\" [permission](#section/Getting-Started/Permissions). - * Get all Companies + * Returns basic information and non-list-specific field data on the requested Company. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/companies/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Companies will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All Organizations directory\" [permission](#section/Getting-Started/Permissions). + * Get a single Company * @param param the request object */ - public getV2CompaniesWithHttpInfo(param: CompaniesApiGetV2CompaniesRequest = {}, options?: ConfigurationOptions): Promise> { - return this.api.getV2CompaniesWithHttpInfo(param.cursor, param.limit, param.ids, param.fieldIds, param.fieldTypes, options).toPromise(); + public v2CompaniesCompanyIdGETWithHttpInfo(param: CompaniesApiV2CompaniesCompanyIdGETRequest, options?: ConfigurationOptions): Promise> { + return this.api.v2CompaniesCompanyIdGETWithHttpInfo(param.companyId, param.fieldIds, param.fieldTypes, options).toPromise(); } /** - * Paginate through Companies in Affinity. Returns basic information and non-list-specific field data on each Company. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/companies/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Companies will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All Organizations directory\" [permission](#section/Getting-Started/Permissions). - * Get all Companies + * Returns basic information and non-list-specific field data on the requested Company. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/companies/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Companies will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All Organizations directory\" [permission](#section/Getting-Started/Permissions). + * Get a single Company * @param param the request object */ - public getV2Companies(param: CompaniesApiGetV2CompaniesRequest = {}, options?: ConfigurationOptions): Promise { - return this.api.getV2Companies(param.cursor, param.limit, param.ids, param.fieldIds, param.fieldTypes, options).toPromise(); + public v2CompaniesCompanyIdGET(param: CompaniesApiV2CompaniesCompanyIdGETRequest, options?: ConfigurationOptions): Promise { + return this.api.v2CompaniesCompanyIdGET(param.companyId, param.fieldIds, param.fieldTypes, options).toPromise(); } /** - * Returns metadata on non-list-specific Company Fields. Use the returned Field IDs to request field data from the GET `/v2/companies` and GET `/v2/companies/{id}` endpoints. - * Get metadata on Company Fields + * Paginate through the List Entries (AKA rows) for the given Company across all Lists. Each List Entry includes field data for the Company, including list-specific field data. Each List Entry also includes metadata about its creation, i.e., when it was added to the List and by whom. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Get a Company\'s List Entries * @param param the request object */ - public getV2CompaniesFieldsWithHttpInfo(param: CompaniesApiGetV2CompaniesFieldsRequest = {}, options?: ConfigurationOptions): Promise> { - return this.api.getV2CompaniesFieldsWithHttpInfo(param.cursor, param.limit, options).toPromise(); + public v2CompaniesCompanyIdListEntriesGETWithHttpInfo(param: CompaniesApiV2CompaniesCompanyIdListEntriesGETRequest, options?: ConfigurationOptions): Promise> { + return this.api.v2CompaniesCompanyIdListEntriesGETWithHttpInfo(param.companyId, param.cursor, param.limit, options).toPromise(); } /** - * Returns metadata on non-list-specific Company Fields. Use the returned Field IDs to request field data from the GET `/v2/companies` and GET `/v2/companies/{id}` endpoints. - * Get metadata on Company Fields + * Paginate through the List Entries (AKA rows) for the given Company across all Lists. Each List Entry includes field data for the Company, including list-specific field data. Each List Entry also includes metadata about its creation, i.e., when it was added to the List and by whom. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Get a Company\'s List Entries * @param param the request object */ - public getV2CompaniesFields(param: CompaniesApiGetV2CompaniesFieldsRequest = {}, options?: ConfigurationOptions): Promise { - return this.api.getV2CompaniesFields(param.cursor, param.limit, options).toPromise(); + public v2CompaniesCompanyIdListEntriesGET(param: CompaniesApiV2CompaniesCompanyIdListEntriesGETRequest, options?: ConfigurationOptions): Promise { + return this.api.v2CompaniesCompanyIdListEntriesGET(param.companyId, param.cursor, param.limit, options).toPromise(); } /** - * Returns basic information and non-list-specific field data on the requested Company. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/companies/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Companies will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All Organizations directory\" [permission](#section/Getting-Started/Permissions). - * Get a single Company + * Paginate through all Lists where the given Company appears as an entry and that you have access to view. Returns basic List information for each List that contains this Company. + * Get a Company\'s Lists * @param param the request object */ - public getV2CompaniesIdWithHttpInfo(param: CompaniesApiGetV2CompaniesIdRequest, options?: ConfigurationOptions): Promise> { - return this.api.getV2CompaniesIdWithHttpInfo(param.id, param.fieldIds, param.fieldTypes, options).toPromise(); + public v2CompaniesCompanyIdListsGETWithHttpInfo(param: CompaniesApiV2CompaniesCompanyIdListsGETRequest, options?: ConfigurationOptions): Promise> { + return this.api.v2CompaniesCompanyIdListsGETWithHttpInfo(param.companyId, param.cursor, param.limit, options).toPromise(); } /** - * Returns basic information and non-list-specific field data on the requested Company. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/companies/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Companies will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All Organizations directory\" [permission](#section/Getting-Started/Permissions). - * Get a single Company + * Paginate through all Lists where the given Company appears as an entry and that you have access to view. Returns basic List information for each List that contains this Company. + * Get a Company\'s Lists * @param param the request object */ - public getV2CompaniesId(param: CompaniesApiGetV2CompaniesIdRequest, options?: ConfigurationOptions): Promise { - return this.api.getV2CompaniesId(param.id, param.fieldIds, param.fieldTypes, options).toPromise(); + public v2CompaniesCompanyIdListsGET(param: CompaniesApiV2CompaniesCompanyIdListsGETRequest, options?: ConfigurationOptions): Promise { + return this.api.v2CompaniesCompanyIdListsGET(param.companyId, param.cursor, param.limit, options).toPromise(); } /** - * Paginate through the List Entries (AKA rows) for the given Company across all Lists. Each List Entry includes field data for the Company, including list-specific field data. Each List Entry also includes metadata about its creation, i.e., when it was added to the List and by whom. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Get a Company\'s List Entries + * | ⚠️ This endpoint is currently in BETA | |--| Returns relevant notes for a given company which includes directly attached notes and notes attached to persons on this company. You can filter notes using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|---------------------------------| | `creator.id` | Filter notes by the creator of the note | `int32` | `=` | `creator.id=1` | | `createdAt` | Filter notes by when it was created | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-02-04T10:48:24Z` | | `updatedAt` | Filter notes by when it was updated | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-02-03T10:48:24Z`| + * Get Notes for a Company * @param param the request object */ - public getV2CompaniesIdListEntriesWithHttpInfo(param: CompaniesApiGetV2CompaniesIdListEntriesRequest, options?: ConfigurationOptions): Promise> { - return this.api.getV2CompaniesIdListEntriesWithHttpInfo(param.id, param.cursor, param.limit, options).toPromise(); + public v2CompaniesCompanyIdNotesGETWithHttpInfo(param: CompaniesApiV2CompaniesCompanyIdNotesGETRequest, options?: ConfigurationOptions): Promise> { + return this.api.v2CompaniesCompanyIdNotesGETWithHttpInfo(param.companyId, param.filter, param.cursor, param.limit, param.totalCount, options).toPromise(); } /** - * Paginate through the List Entries (AKA rows) for the given Company across all Lists. Each List Entry includes field data for the Company, including list-specific field data. Each List Entry also includes metadata about its creation, i.e., when it was added to the List and by whom. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Get a Company\'s List Entries + * | ⚠️ This endpoint is currently in BETA | |--| Returns relevant notes for a given company which includes directly attached notes and notes attached to persons on this company. You can filter notes using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|---------------------------------| | `creator.id` | Filter notes by the creator of the note | `int32` | `=` | `creator.id=1` | | `createdAt` | Filter notes by when it was created | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-02-04T10:48:24Z` | | `updatedAt` | Filter notes by when it was updated | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-02-03T10:48:24Z`| + * Get Notes for a Company * @param param the request object */ - public getV2CompaniesIdListEntries(param: CompaniesApiGetV2CompaniesIdListEntriesRequest, options?: ConfigurationOptions): Promise { - return this.api.getV2CompaniesIdListEntries(param.id, param.cursor, param.limit, options).toPromise(); + public v2CompaniesCompanyIdNotesGET(param: CompaniesApiV2CompaniesCompanyIdNotesGETRequest, options?: ConfigurationOptions): Promise { + return this.api.v2CompaniesCompanyIdNotesGET(param.companyId, param.filter, param.cursor, param.limit, param.totalCount, options).toPromise(); } /** - * Returns metadata for all the Lists on which the given Company appears. - * Get a Company\'s Lists + * Returns metadata on non-list-specific Company Fields. Use the returned Field IDs to request field data from the GET `/v2/companies` and GET `/v2/companies/{id}` endpoints. + * Get metadata on Company Fields * @param param the request object */ - public getV2CompaniesIdListsWithHttpInfo(param: CompaniesApiGetV2CompaniesIdListsRequest, options?: ConfigurationOptions): Promise> { - return this.api.getV2CompaniesIdListsWithHttpInfo(param.id, param.cursor, param.limit, options).toPromise(); + public v2CompaniesFieldsGETWithHttpInfo(param: CompaniesApiV2CompaniesFieldsGETRequest = {}, options?: ConfigurationOptions): Promise> { + return this.api.v2CompaniesFieldsGETWithHttpInfo(param.cursor, param.limit, options).toPromise(); } /** - * Returns metadata for all the Lists on which the given Company appears. - * Get a Company\'s Lists + * Returns metadata on non-list-specific Company Fields. Use the returned Field IDs to request field data from the GET `/v2/companies` and GET `/v2/companies/{id}` endpoints. + * Get metadata on Company Fields * @param param the request object */ - public getV2CompaniesIdLists(param: CompaniesApiGetV2CompaniesIdListsRequest, options?: ConfigurationOptions): Promise { - return this.api.getV2CompaniesIdLists(param.id, param.cursor, param.limit, options).toPromise(); + public v2CompaniesFieldsGET(param: CompaniesApiV2CompaniesFieldsGETRequest = {}, options?: ConfigurationOptions): Promise { + return this.api.v2CompaniesFieldsGET(param.cursor, param.limit, options).toPromise(); } -} - -import { ObservableListsApi } from "./ObservableAPI.ts"; -import { ListsApiRequestFactory, ListsApiResponseProcessor} from "../apis/ListsApi.ts"; + /** + * Paginate through Companies in Affinity. Returns basic information and non-list-specific field data on each Company. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/companies/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Companies will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All Organizations directory\" [permission](#section/Getting-Started/Permissions). + * Get all Companies + * @param param the request object + */ + public v2CompaniesGETWithHttpInfo(param: CompaniesApiV2CompaniesGETRequest = {}, options?: ConfigurationOptions): Promise> { + return this.api.v2CompaniesGETWithHttpInfo(param.cursor, param.limit, param.ids, param.fieldIds, param.fieldTypes, options).toPromise(); + } -export interface ListsApiGetV2ListsListidSavedViewsRequest { /** - * List ID - * Minimum: 1 - * Maximum: -9223372036854775616 - * Defaults to: undefined - * @type number - * @memberof ListsApigetV2ListsListidSavedViews + * Paginate through Companies in Affinity. Returns basic information and non-list-specific field data on each Company. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/companies/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Companies will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All Organizations directory\" [permission](#section/Getting-Started/Permissions). + * Get all Companies + * @param param the request object */ - listId: number + public v2CompaniesGET(param: CompaniesApiV2CompaniesGETRequest = {}, options?: ConfigurationOptions): Promise { + return this.api.v2CompaniesGET(param.cursor, param.limit, param.ids, param.fieldIds, param.fieldTypes, options).toPromise(); + } + +} + +import { ObservableCompanyMergesApi } from "./ObservableAPI.ts"; +import { CompanyMergesApiRequestFactory, CompanyMergesApiResponseProcessor} from "../apis/CompanyMergesApi.ts"; + +export interface CompanyMergesApiV2CompanyMergesGETRequest { /** * Cursor for the next or previous page * Defaults to: undefined * @type string - * @memberof ListsApigetV2ListsListidSavedViews + * @memberof CompanyMergesApiv2CompanyMergesGET */ cursor?: string /** @@ -399,56 +612,45 @@ export interface ListsApiGetV2ListsListidSavedViewsRequest { * Maximum: 100 * Defaults to: 100 * @type number - * @memberof ListsApigetV2ListsListidSavedViews + * @memberof CompanyMergesApiv2CompanyMergesGET */ limit?: number -} - -export interface ListsApiGetV2ListsListidSavedViewsViewidRequest { - /** - * List ID - * Minimum: 1 - * Maximum: -9223372036854775616 - * Defaults to: undefined - * @type number - * @memberof ListsApigetV2ListsListidSavedViewsViewid - */ - listId: number /** - * Saved view ID - * Minimum: 1 - * Maximum: -9223372036854775616 + * Filter company merges using Affinity Filtering Language * Defaults to: undefined - * @type number - * @memberof ListsApigetV2ListsListidSavedViewsViewid + * @type string + * @memberof CompanyMergesApiv2CompanyMergesGET */ - viewId: number + filter?: string } -export interface ListsApiGetV2ListsListidSavedViewsViewidListEntriesRequest { +export interface CompanyMergesApiV2CompanyMergesMergeIdGETRequest { /** - * List ID + * Company merge ID * Minimum: 1 - * Maximum: -9223372036854775616 + * Maximum: 9007199254740991 * Defaults to: undefined * @type number - * @memberof ListsApigetV2ListsListidSavedViewsViewidListEntries + * @memberof CompanyMergesApiv2CompanyMergesMergeIdGET */ - listId: number + mergeId: number +} + +export interface CompanyMergesApiV2CompanyMergesPOSTRequest { /** - * Saved view ID - * Minimum: 1 - * Maximum: -9223372036854775616 - * Defaults to: undefined - * @type number - * @memberof ListsApigetV2ListsListidSavedViewsViewidListEntries + * + * @type CompanyMergeRequest + * @memberof CompanyMergesApiv2CompanyMergesPOST */ - viewId: number + companyMergeRequest: CompanyMergeRequest +} + +export interface CompanyMergesApiV2TasksCompanyMergesGETRequest { /** * Cursor for the next or previous page * Defaults to: undefined * @type string - * @memberof ListsApigetV2ListsListidSavedViewsViewidListEntries + * @memberof CompanyMergesApiv2TasksCompanyMergesGET */ cursor?: string /** @@ -457,75 +659,250 @@ export interface ListsApiGetV2ListsListidSavedViewsViewidListEntriesRequest { * Maximum: 100 * Defaults to: 100 * @type number - * @memberof ListsApigetV2ListsListidSavedViewsViewidListEntries + * @memberof CompanyMergesApiv2TasksCompanyMergesGET */ limit?: number -} - -export interface ListsApiV2ListsGETRequest { /** - * Cursor for the next or previous page + * Filter tasks using Affinity Filtering Language * Defaults to: undefined * @type string - * @memberof ListsApiv2ListsGET - */ - cursor?: string - /** - * Number of items to include in the page - * Minimum: 1 - * Maximum: 100 - * Defaults to: 100 - * @type number - * @memberof ListsApiv2ListsGET + * @memberof CompanyMergesApiv2TasksCompanyMergesGET */ - limit?: number + filter?: string } -export interface ListsApiV2ListsListIdFieldsGETRequest { - /** - * List ID - * Minimum: 1 - * Maximum: -9223372036854775616 - * Defaults to: undefined - * @type number - * @memberof ListsApiv2ListsListIdFieldsGET - */ - listId: number +export interface CompanyMergesApiV2TasksCompanyMergesTaskIdGETRequest { /** - * Cursor for the next or previous page + * Company merge task ID * Defaults to: undefined * @type string - * @memberof ListsApiv2ListsListIdFieldsGET - */ - cursor?: string - /** - * Number of items to include in the page - * Minimum: 1 - * Maximum: 100 - * Defaults to: 100 - * @type number - * @memberof ListsApiv2ListsListIdFieldsGET + * @memberof CompanyMergesApiv2TasksCompanyMergesTaskIdGET */ - limit?: number + taskId: string } -export interface ListsApiV2ListsListIdGETRequest { +export class ObjectCompanyMergesApi { + private api: ObservableCompanyMergesApi + + public constructor(configuration: Configuration, requestFactory?: CompanyMergesApiRequestFactory, responseProcessor?: CompanyMergesApiResponseProcessor) { + this.api = new ObservableCompanyMergesApi(configuration, requestFactory, responseProcessor); + } + /** - * List ID - * Minimum: 1 - * Maximum: -9223372036854775616 - * Defaults to: undefined - * @type number - * @memberof ListsApiv2ListsListIdGET + * Retrieve paginated company merges for the organization. Returns all company merges initiated by users in your organization, including their current status, the companies involved, and merge details. You can filter company merges using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties: | Property | Type | Operators | Values | Examples | |----------|------|-----------|--------|----------| | `status` | `enum` | `=` | `in-progress`, `success`, `failed` | `status=failed` | | `taskId` | `string` | `=` | | `taskId=789e0123-e45b-67c8-d901-234567890123` | Company merges are returned in reverse chronological order (most recent first). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get All Company Merges + * @param param the request object */ - listId: number -} + public v2CompanyMergesGETWithHttpInfo(param: CompanyMergesApiV2CompanyMergesGETRequest = {}, options?: ConfigurationOptions): Promise> { + return this.api.v2CompanyMergesGETWithHttpInfo(param.cursor, param.limit, param.filter, options).toPromise(); + } -export interface ListsApiV2ListsListIdListEntriesGETRequest { /** - * List ID + * Retrieve paginated company merges for the organization. Returns all company merges initiated by users in your organization, including their current status, the companies involved, and merge details. You can filter company merges using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties: | Property | Type | Operators | Values | Examples | |----------|------|-----------|--------|----------| | `status` | `enum` | `=` | `in-progress`, `success`, `failed` | `status=failed` | | `taskId` | `string` | `=` | | `taskId=789e0123-e45b-67c8-d901-234567890123` | Company merges are returned in reverse chronological order (most recent first). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get All Company Merges + * @param param the request object + */ + public v2CompanyMergesGET(param: CompanyMergesApiV2CompanyMergesGETRequest = {}, options?: ConfigurationOptions): Promise { + return this.api.v2CompanyMergesGET(param.cursor, param.limit, param.filter, options).toPromise(); + } + + /** + * Retrieve the status and details of a specific company merge. Returns information about the company merge including its current status, the companies involved, timestamps, and any error information if the merge failed. The `mergeId` can be obtained from the response of the [Get All Company Merges](#tag/companyMerges/operation/v2_company-merges__GET) endpoint, or by filtering company merges by task ID using `/v2/company-merges?filter=taskId={taskId}` after initiating a merge. Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get Company Merge + * @param param the request object + */ + public v2CompanyMergesMergeIdGETWithHttpInfo(param: CompanyMergesApiV2CompanyMergesMergeIdGETRequest, options?: ConfigurationOptions): Promise> { + return this.api.v2CompanyMergesMergeIdGETWithHttpInfo(param.mergeId, options).toPromise(); + } + + /** + * Retrieve the status and details of a specific company merge. Returns information about the company merge including its current status, the companies involved, timestamps, and any error information if the merge failed. The `mergeId` can be obtained from the response of the [Get All Company Merges](#tag/companyMerges/operation/v2_company-merges__GET) endpoint, or by filtering company merges by task ID using `/v2/company-merges?filter=taskId={taskId}` after initiating a merge. Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get Company Merge + * @param param the request object + */ + public v2CompanyMergesMergeIdGET(param: CompanyMergesApiV2CompanyMergesMergeIdGETRequest, options?: ConfigurationOptions): Promise { + return this.api.v2CompanyMergesMergeIdGET(param.mergeId, options).toPromise(); + } + + /** + * Initiate a company merge to combine a duplicate company profile into a primary company profile. This is an asynchronous process that will merge all data from the duplicate company into the primary company. Once the merge is initiated, you can track its progress using the returned [task URL](#tag/companyMerges/operation/v2_tasks_company-merges_taskId__GET). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Initiate Company Merge + * @param param the request object + */ + public v2CompanyMergesPOSTWithHttpInfo(param: CompanyMergesApiV2CompanyMergesPOSTRequest, options?: ConfigurationOptions): Promise> { + return this.api.v2CompanyMergesPOSTWithHttpInfo(param.companyMergeRequest, options).toPromise(); + } + + /** + * Initiate a company merge to combine a duplicate company profile into a primary company profile. This is an asynchronous process that will merge all data from the duplicate company into the primary company. Once the merge is initiated, you can track its progress using the returned [task URL](#tag/companyMerges/operation/v2_tasks_company-merges_taskId__GET). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Initiate Company Merge + * @param param the request object + */ + public v2CompanyMergesPOST(param: CompanyMergesApiV2CompanyMergesPOSTRequest, options?: ConfigurationOptions): Promise { + return this.api.v2CompanyMergesPOST(param.companyMergeRequest, options).toPromise(); + } + + /** + * Retrieve paginated company merge tasks for the organization. Returns all merge tasks initiated by users in your organization, including their current status, the companies involved, and task details. You can filter tasks using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties: | Property | Type | Operators | Values | Examples | |----------|------|-----------|--------|----------| | `status` | `enum` | `=` | `in-progress`, `success`, `failed` | `status=failed` | Tasks are returned in reverse chronological order (most recent first). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get All Company Merge Tasks + * @param param the request object + */ + public v2TasksCompanyMergesGETWithHttpInfo(param: CompanyMergesApiV2TasksCompanyMergesGETRequest = {}, options?: ConfigurationOptions): Promise> { + return this.api.v2TasksCompanyMergesGETWithHttpInfo(param.cursor, param.limit, param.filter, options).toPromise(); + } + + /** + * Retrieve paginated company merge tasks for the organization. Returns all merge tasks initiated by users in your organization, including their current status, the companies involved, and task details. You can filter tasks using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties: | Property | Type | Operators | Values | Examples | |----------|------|-----------|--------|----------| | `status` | `enum` | `=` | `in-progress`, `success`, `failed` | `status=failed` | Tasks are returned in reverse chronological order (most recent first). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get All Company Merge Tasks + * @param param the request object + */ + public v2TasksCompanyMergesGET(param: CompanyMergesApiV2TasksCompanyMergesGETRequest = {}, options?: ConfigurationOptions): Promise { + return this.api.v2TasksCompanyMergesGET(param.cursor, param.limit, param.filter, options).toPromise(); + } + + /** + * Retrieve the status and details of a specific task for company merges. Returns information about the company merges for a specific task including its overall status, number of merges in-progress, completed, and failed. Detailed information about individual merges for this task can be found by querying: `/v2/company-merges?filter=taskId={taskId}` See [Company Merges](#tag/companyMerges/operation/v2_company-merges__GET) for more details. Task statuses: - `in-progress`: The merge task is currently being processed. - `success`: The merge task completed successfully. - `failed`: The merge task failed. Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get Company Merge Task + * @param param the request object + */ + public v2TasksCompanyMergesTaskIdGETWithHttpInfo(param: CompanyMergesApiV2TasksCompanyMergesTaskIdGETRequest, options?: ConfigurationOptions): Promise> { + return this.api.v2TasksCompanyMergesTaskIdGETWithHttpInfo(param.taskId, options).toPromise(); + } + + /** + * Retrieve the status and details of a specific task for company merges. Returns information about the company merges for a specific task including its overall status, number of merges in-progress, completed, and failed. Detailed information about individual merges for this task can be found by querying: `/v2/company-merges?filter=taskId={taskId}` See [Company Merges](#tag/companyMerges/operation/v2_company-merges__GET) for more details. Task statuses: - `in-progress`: The merge task is currently being processed. - `success`: The merge task completed successfully. - `failed`: The merge task failed. Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get Company Merge Task + * @param param the request object + */ + public v2TasksCompanyMergesTaskIdGET(param: CompanyMergesApiV2TasksCompanyMergesTaskIdGETRequest, options?: ConfigurationOptions): Promise { + return this.api.v2TasksCompanyMergesTaskIdGET(param.taskId, options).toPromise(); + } + +} + +import { ObservableEmailsApi } from "./ObservableAPI.ts"; +import { EmailsApiRequestFactory, EmailsApiResponseProcessor} from "../apis/EmailsApi.ts"; + +export interface EmailsApiV2EmailsGETRequest { + /** + * Cursor for the next or previous page + * Defaults to: undefined + * @type string + * @memberof EmailsApiv2EmailsGET + */ + cursor?: string + /** + * Number of items to include in the page + * Minimum: 1 + * Maximum: 100 + * Defaults to: 100 + * @type number + * @memberof EmailsApiv2EmailsGET + */ + limit?: number + /** + * Filter options + * Defaults to: undefined + * @type string + * @memberof EmailsApiv2EmailsGET + */ + filter?: string +} + +export class ObjectEmailsApi { + private api: ObservableEmailsApi + + public constructor(configuration: Configuration, requestFactory?: EmailsApiRequestFactory, responseProcessor?: EmailsApiResponseProcessor) { + this.api = new ObservableEmailsApi(configuration, requestFactory, responseProcessor); + } + + /** + * Paginate through all emails in Affinity. Returns basic information about the email interaction and its participants. Will only return emails or subject lines that the current authenticated user has permission to see. You can filter emails using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|----------------------------------| | `id` | Unique identifier for Emails | `int64` | `=` | `id=1` | | `sentAt` | When the Email was sent at | `datetime` | `>`, `<`, `>=`, `<=` | `sentAt>2025-01-01T01:00:00Z` | | `createdAt` | When the Email was created in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-01-01T01:00:00Z` | | `updatedAt` | When the Email was updated in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-01-01T01:00:00Z`| + * Get metadata on all Emails + * @param param the request object + */ + public v2EmailsGETWithHttpInfo(param: EmailsApiV2EmailsGETRequest = {}, options?: ConfigurationOptions): Promise> { + return this.api.v2EmailsGETWithHttpInfo(param.cursor, param.limit, param.filter, options).toPromise(); + } + + /** + * Paginate through all emails in Affinity. Returns basic information about the email interaction and its participants. Will only return emails or subject lines that the current authenticated user has permission to see. You can filter emails using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|----------------------------------| | `id` | Unique identifier for Emails | `int64` | `=` | `id=1` | | `sentAt` | When the Email was sent at | `datetime` | `>`, `<`, `>=`, `<=` | `sentAt>2025-01-01T01:00:00Z` | | `createdAt` | When the Email was created in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-01-01T01:00:00Z` | | `updatedAt` | When the Email was updated in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-01-01T01:00:00Z`| + * Get metadata on all Emails + * @param param the request object + */ + public v2EmailsGET(param: EmailsApiV2EmailsGETRequest = {}, options?: ConfigurationOptions): Promise { + return this.api.v2EmailsGET(param.cursor, param.limit, param.filter, options).toPromise(); + } + +} + +import { ObservableListsApi } from "./ObservableAPI.ts"; +import { ListsApiRequestFactory, ListsApiResponseProcessor} from "../apis/ListsApi.ts"; + +export interface ListsApiV2ListsGETRequest { + /** + * Cursor for the next or previous page + * Defaults to: undefined + * @type string + * @memberof ListsApiv2ListsGET + */ + cursor?: string + /** + * Number of items to include in the page + * Minimum: 1 + * Maximum: 100 + * Defaults to: 100 + * @type number + * @memberof ListsApiv2ListsGET + */ + limit?: number +} + +export interface ListsApiV2ListsListIdFieldsGETRequest { + /** + * List ID + * Minimum: 1 + * Maximum: 9223372036854776000 + * Defaults to: undefined + * @type number + * @memberof ListsApiv2ListsListIdFieldsGET + */ + listId: number + /** + * Cursor for the next or previous page + * Defaults to: undefined + * @type string + * @memberof ListsApiv2ListsListIdFieldsGET + */ + cursor?: string + /** + * Number of items to include in the page + * Minimum: 1 + * Maximum: 100 + * Defaults to: 100 + * @type number + * @memberof ListsApiv2ListsListIdFieldsGET + */ + limit?: number +} + +export interface ListsApiV2ListsListIdGETRequest { + /** + * List ID + * Minimum: 1 + * Maximum: 9223372036854776000 + * Defaults to: undefined + * @type number + * @memberof ListsApiv2ListsListIdGET + */ + listId: number +} + +export interface ListsApiV2ListsListIdListEntriesGETRequest { + /** + * List ID * Minimum: 1 - * Maximum: -9223372036854775616 + * Maximum: 9223372036854776000 * Defaults to: undefined * @type number * @memberof ListsApiv2ListsListIdListEntriesGET @@ -567,7 +944,7 @@ export interface ListsApiV2ListsListIdListEntriesListEntryIdFieldsFieldIdGETRequ /** * List ID * Minimum: 1 - * Maximum: -9223372036854775616 + * Maximum: 9223372036854776000 * Defaults to: undefined * @type number * @memberof ListsApiv2ListsListIdListEntriesListEntryIdFieldsFieldIdGET @@ -576,7 +953,7 @@ export interface ListsApiV2ListsListIdListEntriesListEntryIdFieldsFieldIdGETRequ /** * List Entry ID * Minimum: 1 - * Maximum: -9223372036854775616 + * Maximum: 9223372036854776000 * Defaults to: undefined * @type number * @memberof ListsApiv2ListsListIdListEntriesListEntryIdFieldsFieldIdGET @@ -595,7 +972,7 @@ export interface ListsApiV2ListsListIdListEntriesListEntryIdFieldsFieldIdPOSTReq /** * List ID * Minimum: 1 - * Maximum: -9223372036854775616 + * Maximum: 9223372036854776000 * Defaults to: undefined * @type number * @memberof ListsApiv2ListsListIdListEntriesListEntryIdFieldsFieldIdPOST @@ -604,7 +981,7 @@ export interface ListsApiV2ListsListIdListEntriesListEntryIdFieldsFieldIdPOSTReq /** * List Entry ID * Minimum: 1 - * Maximum: -9223372036854775616 + * Maximum: 9223372036854776000 * Defaults to: undefined * @type number * @memberof ListsApiv2ListsListIdListEntriesListEntryIdFieldsFieldIdPOST @@ -629,7 +1006,7 @@ export interface ListsApiV2ListsListIdListEntriesListEntryIdFieldsGETRequest { /** * List ID * Minimum: 1 - * Maximum: -9223372036854775616 + * Maximum: 9223372036854776000 * Defaults to: undefined * @type number * @memberof ListsApiv2ListsListIdListEntriesListEntryIdFieldsGET @@ -638,7 +1015,7 @@ export interface ListsApiV2ListsListIdListEntriesListEntryIdFieldsGETRequest { /** * List Entry ID * Minimum: 1 - * Maximum: -9223372036854775616 + * Maximum: 9223372036854776000 * Defaults to: undefined * @type number * @memberof ListsApiv2ListsListIdListEntriesListEntryIdFieldsGET @@ -680,7 +1057,7 @@ export interface ListsApiV2ListsListIdListEntriesListEntryIdFieldsPATCHRequest { /** * List ID * Minimum: 1 - * Maximum: -9223372036854775616 + * Maximum: 9223372036854776000 * Defaults to: undefined * @type number * @memberof ListsApiv2ListsListIdListEntriesListEntryIdFieldsPATCH @@ -689,7 +1066,7 @@ export interface ListsApiV2ListsListIdListEntriesListEntryIdFieldsPATCHRequest { /** * List Entry ID * Minimum: 1 - * Maximum: -9223372036854775616 + * Maximum: 9223372036854776000 * Defaults to: undefined * @type number * @memberof ListsApiv2ListsListIdListEntriesListEntryIdFieldsPATCH @@ -707,7 +1084,7 @@ export interface ListsApiV2ListsListIdListEntriesListEntryIdGETRequest { /** * List ID * Minimum: 1 - * Maximum: -9223372036854775616 + * Maximum: 9223372036854776000 * Defaults to: undefined * @type number * @memberof ListsApiv2ListsListIdListEntriesListEntryIdGET @@ -716,7 +1093,7 @@ export interface ListsApiV2ListsListIdListEntriesListEntryIdGETRequest { /** * List Entry ID * Minimum: 1 - * Maximum: -9223372036854775616 + * Maximum: 9223372036854776000 * Defaults to: undefined * @type number * @memberof ListsApiv2ListsListIdListEntriesListEntryIdGET @@ -738,69 +1115,101 @@ export interface ListsApiV2ListsListIdListEntriesListEntryIdGETRequest { fieldTypes?: Array<'enriched' | 'global' | 'list' | 'relationship-intelligence'> } -export class ObjectListsApi { - private api: ObservableListsApi - - public constructor(configuration: Configuration, requestFactory?: ListsApiRequestFactory, responseProcessor?: ListsApiResponseProcessor) { - this.api = new ObservableListsApi(configuration, requestFactory, responseProcessor); - } - +export interface ListsApiV2ListsListIdSavedViewsGETRequest { /** - * Returns metadata on the Saved Views on a List. - * Get metadata on Saved Views - * @param param the request object + * List ID + * Minimum: 1 + * Maximum: 9223372036854776000 + * Defaults to: undefined + * @type number + * @memberof ListsApiv2ListsListIdSavedViewsGET */ - public getV2ListsListidSavedViewsWithHttpInfo(param: ListsApiGetV2ListsListidSavedViewsRequest, options?: ConfigurationOptions): Promise> { - return this.api.getV2ListsListidSavedViewsWithHttpInfo(param.listId, param.cursor, param.limit, options).toPromise(); - } - + listId: number /** - * Returns metadata on the Saved Views on a List. - * Get metadata on Saved Views - * @param param the request object + * Cursor for the next or previous page + * Defaults to: undefined + * @type string + * @memberof ListsApiv2ListsListIdSavedViewsGET */ - public getV2ListsListidSavedViews(param: ListsApiGetV2ListsListidSavedViewsRequest, options?: ConfigurationOptions): Promise { - return this.api.getV2ListsListidSavedViews(param.listId, param.cursor, param.limit, options).toPromise(); - } - + cursor?: string /** - * Returns metadata on a single Saved View. - * Get metadata on a single Saved View - * @param param the request object + * Number of items to include in the page + * Minimum: 1 + * Maximum: 100 + * Defaults to: 100 + * @type number + * @memberof ListsApiv2ListsListIdSavedViewsGET */ - public getV2ListsListidSavedViewsViewidWithHttpInfo(param: ListsApiGetV2ListsListidSavedViewsViewidRequest, options?: ConfigurationOptions): Promise> { - return this.api.getV2ListsListidSavedViewsViewidWithHttpInfo(param.listId, param.viewId, options).toPromise(); - } + limit?: number +} +export interface ListsApiV2ListsListIdSavedViewsViewIdGETRequest { /** - * Returns metadata on a single Saved View. - * Get metadata on a single Saved View - * @param param the request object + * List ID + * Minimum: 1 + * Maximum: 9223372036854776000 + * Defaults to: undefined + * @type number + * @memberof ListsApiv2ListsListIdSavedViewsViewIdGET */ - public getV2ListsListidSavedViewsViewid(param: ListsApiGetV2ListsListidSavedViewsViewidRequest, options?: ConfigurationOptions): Promise { - return this.api.getV2ListsListidSavedViewsViewid(param.listId, param.viewId, options).toPromise(); - } - + listId: number /** - * Paginate through the List Entries (AKA rows) on a given Saved View. Use this endpoint when you need to filter entities or only want **some** field data to be returned: This endpoint respects the filters set on a Saved View via web app, and only returns field data corresponding to the columns that have been pulled into the Saved View via web app. Though this endpoint respects the Saved View\'s filters and column/Field selection, it does not yet preserve sort order. This endpoint also only supports **sheet-type Saved Views**, and not board- or dashboard-type Saved Views. See the [Data Model](#section/Data-Model) section for more information about Saved Views. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Get all List Entries on a Saved View - * @param param the request object + * Saved view ID + * Minimum: 1 + * Maximum: 9223372036854776000 + * Defaults to: undefined + * @type number + * @memberof ListsApiv2ListsListIdSavedViewsViewIdGET */ - public getV2ListsListidSavedViewsViewidListEntriesWithHttpInfo(param: ListsApiGetV2ListsListidSavedViewsViewidListEntriesRequest, options?: ConfigurationOptions): Promise> { - return this.api.getV2ListsListidSavedViewsViewidListEntriesWithHttpInfo(param.listId, param.viewId, param.cursor, param.limit, options).toPromise(); - } + viewId: number +} +export interface ListsApiV2ListsListIdSavedViewsViewIdListEntriesGETRequest { /** - * Paginate through the List Entries (AKA rows) on a given Saved View. Use this endpoint when you need to filter entities or only want **some** field data to be returned: This endpoint respects the filters set on a Saved View via web app, and only returns field data corresponding to the columns that have been pulled into the Saved View via web app. Though this endpoint respects the Saved View\'s filters and column/Field selection, it does not yet preserve sort order. This endpoint also only supports **sheet-type Saved Views**, and not board- or dashboard-type Saved Views. See the [Data Model](#section/Data-Model) section for more information about Saved Views. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Get all List Entries on a Saved View - * @param param the request object + * List ID + * Minimum: 1 + * Maximum: 9223372036854776000 + * Defaults to: undefined + * @type number + * @memberof ListsApiv2ListsListIdSavedViewsViewIdListEntriesGET + */ + listId: number + /** + * Saved view ID + * Minimum: 1 + * Maximum: 9223372036854776000 + * Defaults to: undefined + * @type number + * @memberof ListsApiv2ListsListIdSavedViewsViewIdListEntriesGET + */ + viewId: number + /** + * Cursor for the next or previous page + * Defaults to: undefined + * @type string + * @memberof ListsApiv2ListsListIdSavedViewsViewIdListEntriesGET + */ + cursor?: string + /** + * Number of items to include in the page + * Minimum: 1 + * Maximum: 100 + * Defaults to: 100 + * @type number + * @memberof ListsApiv2ListsListIdSavedViewsViewIdListEntriesGET */ - public getV2ListsListidSavedViewsViewidListEntries(param: ListsApiGetV2ListsListidSavedViewsViewidListEntriesRequest, options?: ConfigurationOptions): Promise { - return this.api.getV2ListsListidSavedViewsViewidListEntries(param.listId, param.viewId, param.cursor, param.limit, options).toPromise(); + limit?: number +} + +export class ObjectListsApi { + private api: ObservableListsApi + + public constructor(configuration: Configuration, requestFactory?: ListsApiRequestFactory, responseProcessor?: ListsApiResponseProcessor) { + this.api = new ObservableListsApi(configuration, requestFactory, responseProcessor); } /** - * Returns metadata on Lists. + * Paginate through all Lists in your organization that you have access to view. Returns basic information about each List, including name, owner, and privacy settings. * Get metadata on all Lists * @param param the request object */ @@ -809,7 +1218,7 @@ export class ObjectListsApi { } /** - * Returns metadata on Lists. + * Paginate through all Lists in your organization that you have access to view. Returns basic information about each List, including name, owner, and privacy settings. * Get metadata on all Lists * @param param the request object */ @@ -836,7 +1245,7 @@ export class ObjectListsApi { } /** - * Returns metadata on a single List. + * Retrieve detailed information about a specific List you have access to view. Returns List configuration including name, owner, privacy settings, and creation details. * Get metadata on a single List * @param param the request object */ @@ -845,7 +1254,7 @@ export class ObjectListsApi { } /** - * Returns metadata on a single List. + * Retrieve detailed information about a specific List you have access to view. Returns List configuration including name, owner, privacy settings, and creation details. * Get metadata on a single List * @param param the request object */ @@ -854,111 +1263,547 @@ export class ObjectListsApi { } /** - * Paginate through the List Entries (AKA rows) on a given List. Returns basic information and field data, including list-specific field data, on each Company, Person, or Opportunity on the List. List Entries also include metadata about their creation, i.e., when they were added to the List and by whom. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/lists/{listId}/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, List Entries will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Get all List Entries on a List + * Paginate through the List Entries (AKA rows) on a given List. Returns basic information and field data, including list-specific field data, on each Company, Person, or Opportunity on the List. List Entries also include metadata about their creation, i.e., when they were added to the List and by whom. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/lists/{listId}/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, List Entries will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Get all List Entries on a List + * @param param the request object + */ + public v2ListsListIdListEntriesGETWithHttpInfo(param: ListsApiV2ListsListIdListEntriesGETRequest, options?: ConfigurationOptions): Promise> { + return this.api.v2ListsListIdListEntriesGETWithHttpInfo(param.listId, param.cursor, param.limit, param.fieldIds, param.fieldTypes, options).toPromise(); + } + + /** + * Paginate through the List Entries (AKA rows) on a given List. Returns basic information and field data, including list-specific field data, on each Company, Person, or Opportunity on the List. List Entries also include metadata about their creation, i.e., when they were added to the List and by whom. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/lists/{listId}/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, List Entries will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Get all List Entries on a List + * @param param the request object + */ + public v2ListsListIdListEntriesGET(param: ListsApiV2ListsListIdListEntriesGETRequest, options?: ConfigurationOptions): Promise { + return this.api.v2ListsListIdListEntriesGET(param.listId, param.cursor, param.limit, param.fieldIds, param.fieldTypes, options).toPromise(); + } + + /** + * Returns a single field value on a list entry. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Get a single field value + * @param param the request object + */ + public v2ListsListIdListEntriesListEntryIdFieldsFieldIdGETWithHttpInfo(param: ListsApiV2ListsListIdListEntriesListEntryIdFieldsFieldIdGETRequest, options?: ConfigurationOptions): Promise> { + return this.api.v2ListsListIdListEntriesListEntryIdFieldsFieldIdGETWithHttpInfo(param.listId, param.listEntryId, param.fieldId, options).toPromise(); + } + + /** + * Returns a single field value on a list entry. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Get a single field value + * @param param the request object + */ + public v2ListsListIdListEntriesListEntryIdFieldsFieldIdGET(param: ListsApiV2ListsListIdListEntriesListEntryIdFieldsFieldIdGETRequest, options?: ConfigurationOptions): Promise { + return this.api.v2ListsListIdListEntriesListEntryIdFieldsFieldIdGET(param.listId, param.listEntryId, param.fieldId, options).toPromise(); + } + + /** + * Update a single field value. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Update a single field value on a List Entry + * @param param the request object + */ + public v2ListsListIdListEntriesListEntryIdFieldsFieldIdPOSTWithHttpInfo(param: ListsApiV2ListsListIdListEntriesListEntryIdFieldsFieldIdPOSTRequest, options?: ConfigurationOptions): Promise> { + return this.api.v2ListsListIdListEntriesListEntryIdFieldsFieldIdPOSTWithHttpInfo(param.listId, param.listEntryId, param.fieldId, param.fieldUpdate, options).toPromise(); + } + + /** + * Update a single field value. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Update a single field value on a List Entry + * @param param the request object + */ + public v2ListsListIdListEntriesListEntryIdFieldsFieldIdPOST(param: ListsApiV2ListsListIdListEntriesListEntryIdFieldsFieldIdPOSTRequest, options?: ConfigurationOptions): Promise { + return this.api.v2ListsListIdListEntriesListEntryIdFieldsFieldIdPOST(param.listId, param.listEntryId, param.fieldId, param.fieldUpdate, options).toPromise(); + } + + /** + * Paginate through all field values on a single list entry. All fields will be included by default. The `ids` and `types` parameters can be used to filter the collection. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Get field values on a single List Entry + * @param param the request object + */ + public v2ListsListIdListEntriesListEntryIdFieldsGETWithHttpInfo(param: ListsApiV2ListsListIdListEntriesListEntryIdFieldsGETRequest, options?: ConfigurationOptions): Promise> { + return this.api.v2ListsListIdListEntriesListEntryIdFieldsGETWithHttpInfo(param.listId, param.listEntryId, param.ids, param.types, param.cursor, param.limit, options).toPromise(); + } + + /** + * Paginate through all field values on a single list entry. All fields will be included by default. The `ids` and `types` parameters can be used to filter the collection. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Get field values on a single List Entry + * @param param the request object + */ + public v2ListsListIdListEntriesListEntryIdFieldsGET(param: ListsApiV2ListsListIdListEntriesListEntryIdFieldsGETRequest, options?: ConfigurationOptions): Promise { + return this.api.v2ListsListIdListEntriesListEntryIdFieldsGET(param.listId, param.listEntryId, param.ids, param.types, param.cursor, param.limit, options).toPromise(); + } + + /** + * Perform batch operations on a list entry\'s fields. Currently the only operation at the endpoint is `update-fields`, which allows you to update multiple field values with a single request. This is equivalent to calling [the single field update](#operation/v2_lists_listId_list-entries_listEntryId_fields_fieldId__POST) endpoint multiple times. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Perform batch operations on a list entry\'s fields + * @param param the request object + */ + public v2ListsListIdListEntriesListEntryIdFieldsPATCHWithHttpInfo(param: ListsApiV2ListsListIdListEntriesListEntryIdFieldsPATCHRequest, options?: ConfigurationOptions): Promise> { + return this.api.v2ListsListIdListEntriesListEntryIdFieldsPATCHWithHttpInfo(param.listId, param.listEntryId, param.body, options).toPromise(); + } + + /** + * Perform batch operations on a list entry\'s fields. Currently the only operation at the endpoint is `update-fields`, which allows you to update multiple field values with a single request. This is equivalent to calling [the single field update](#operation/v2_lists_listId_list-entries_listEntryId_fields_fieldId__POST) endpoint multiple times. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Perform batch operations on a list entry\'s fields + * @param param the request object + */ + public v2ListsListIdListEntriesListEntryIdFieldsPATCH(param: ListsApiV2ListsListIdListEntriesListEntryIdFieldsPATCHRequest, options?: ConfigurationOptions): Promise { + return this.api.v2ListsListIdListEntriesListEntryIdFieldsPATCH(param.listId, param.listEntryId, param.body, options).toPromise(); + } + + /** + * Retrieve a single list entry. Returns basic information and field data, including list-specific field data. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/lists/{listId}/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, the List Entry will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Get a single List Entry on a List + * @param param the request object + */ + public v2ListsListIdListEntriesListEntryIdGETWithHttpInfo(param: ListsApiV2ListsListIdListEntriesListEntryIdGETRequest, options?: ConfigurationOptions): Promise> { + return this.api.v2ListsListIdListEntriesListEntryIdGETWithHttpInfo(param.listId, param.listEntryId, param.fieldIds, param.fieldTypes, options).toPromise(); + } + + /** + * Retrieve a single list entry. Returns basic information and field data, including list-specific field data. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/lists/{listId}/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, the List Entry will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Get a single List Entry on a List + * @param param the request object + */ + public v2ListsListIdListEntriesListEntryIdGET(param: ListsApiV2ListsListIdListEntriesListEntryIdGETRequest, options?: ConfigurationOptions): Promise { + return this.api.v2ListsListIdListEntriesListEntryIdGET(param.listId, param.listEntryId, param.fieldIds, param.fieldTypes, options).toPromise(); + } + + /** + * Paginate through all Saved Views you have access to view for a specific List. Returns Saved View configurations including name, column settings, and owner information. + * Get metadata on Saved Views + * @param param the request object + */ + public v2ListsListIdSavedViewsGETWithHttpInfo(param: ListsApiV2ListsListIdSavedViewsGETRequest, options?: ConfigurationOptions): Promise> { + return this.api.v2ListsListIdSavedViewsGETWithHttpInfo(param.listId, param.cursor, param.limit, options).toPromise(); + } + + /** + * Paginate through all Saved Views you have access to view for a specific List. Returns Saved View configurations including name, column settings, and owner information. + * Get metadata on Saved Views + * @param param the request object + */ + public v2ListsListIdSavedViewsGET(param: ListsApiV2ListsListIdSavedViewsGETRequest, options?: ConfigurationOptions): Promise { + return this.api.v2ListsListIdSavedViewsGET(param.listId, param.cursor, param.limit, options).toPromise(); + } + + /** + * Retrieve detailed information about a specific Saved View you have access to view. Returns complete Saved View configuration including name, sorting, and column visibility settings. + * Get metadata on a single Saved View + * @param param the request object + */ + public v2ListsListIdSavedViewsViewIdGETWithHttpInfo(param: ListsApiV2ListsListIdSavedViewsViewIdGETRequest, options?: ConfigurationOptions): Promise> { + return this.api.v2ListsListIdSavedViewsViewIdGETWithHttpInfo(param.listId, param.viewId, options).toPromise(); + } + + /** + * Retrieve detailed information about a specific Saved View you have access to view. Returns complete Saved View configuration including name, sorting, and column visibility settings. + * Get metadata on a single Saved View + * @param param the request object + */ + public v2ListsListIdSavedViewsViewIdGET(param: ListsApiV2ListsListIdSavedViewsViewIdGETRequest, options?: ConfigurationOptions): Promise { + return this.api.v2ListsListIdSavedViewsViewIdGET(param.listId, param.viewId, options).toPromise(); + } + + /** + * Paginate through the List Entries (AKA rows) on a given Saved View. Use this endpoint when you need to filter entities or only want **some** field data to be returned: This endpoint respects the filters set on a Saved View via web app, and only returns field data corresponding to the columns that have been pulled into the Saved View via web app. Though this endpoint respects the Saved View\'s filters and column/Field selection, it does not yet preserve sort order. This endpoint also only supports **sheet-type Saved Views**, and not board- or dashboard-type Saved Views. See the [Data Model](#section/Data-Model) section for more information about Saved Views. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Get all List Entries on a Saved View + * @param param the request object + */ + public v2ListsListIdSavedViewsViewIdListEntriesGETWithHttpInfo(param: ListsApiV2ListsListIdSavedViewsViewIdListEntriesGETRequest, options?: ConfigurationOptions): Promise> { + return this.api.v2ListsListIdSavedViewsViewIdListEntriesGETWithHttpInfo(param.listId, param.viewId, param.cursor, param.limit, options).toPromise(); + } + + /** + * Paginate through the List Entries (AKA rows) on a given Saved View. Use this endpoint when you need to filter entities or only want **some** field data to be returned: This endpoint respects the filters set on a Saved View via web app, and only returns field data corresponding to the columns that have been pulled into the Saved View via web app. Though this endpoint respects the Saved View\'s filters and column/Field selection, it does not yet preserve sort order. This endpoint also only supports **sheet-type Saved Views**, and not board- or dashboard-type Saved Views. See the [Data Model](#section/Data-Model) section for more information about Saved Views. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Get all List Entries on a Saved View + * @param param the request object + */ + public v2ListsListIdSavedViewsViewIdListEntriesGET(param: ListsApiV2ListsListIdSavedViewsViewIdListEntriesGETRequest, options?: ConfigurationOptions): Promise { + return this.api.v2ListsListIdSavedViewsViewIdListEntriesGET(param.listId, param.viewId, param.cursor, param.limit, options).toPromise(); + } + +} + +import { ObservableMeetingsApi } from "./ObservableAPI.ts"; +import { MeetingsApiRequestFactory, MeetingsApiResponseProcessor} from "../apis/MeetingsApi.ts"; + +export interface MeetingsApiV2MeetingsGETRequest { + /** + * Cursor for the next or previous page + * Defaults to: undefined + * @type string + * @memberof MeetingsApiv2MeetingsGET + */ + cursor?: string + /** + * Number of items to include in the page + * Minimum: 1 + * Maximum: 100 + * Defaults to: 100 + * @type number + * @memberof MeetingsApiv2MeetingsGET + */ + limit?: number + /** + * Filter options + * Defaults to: undefined + * @type string + * @memberof MeetingsApiv2MeetingsGET + */ + filter?: string +} + +export class ObjectMeetingsApi { + private api: ObservableMeetingsApi + + public constructor(configuration: Configuration, requestFactory?: MeetingsApiRequestFactory, responseProcessor?: MeetingsApiResponseProcessor) { + this.api = new ObservableMeetingsApi(configuration, requestFactory, responseProcessor); + } + + /** + * Paginate through all Meetings in Affinity. Returns basic information about past and future meeting interactions and its attendees. You can filter meetings using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|----------------------------------| | `id` | Unique identifier for Meetings | `int64` | `=` | `id=1` | | `startTime` | Start time of when Meeting was scheduled | `datetime` | `>`, `<`, `>=`, `<=` | `startTime>2025-01-01T01:00:00Z` | | `createdAt` | When the Meeting was created in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-01-01T01:00:00Z` | | `updatedAt` | When the Meeting was updated in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-01-01T01:00:00Z`| + * Get metadata on all Meetings + * @param param the request object + */ + public v2MeetingsGETWithHttpInfo(param: MeetingsApiV2MeetingsGETRequest = {}, options?: ConfigurationOptions): Promise> { + return this.api.v2MeetingsGETWithHttpInfo(param.cursor, param.limit, param.filter, options).toPromise(); + } + + /** + * Paginate through all Meetings in Affinity. Returns basic information about past and future meeting interactions and its attendees. You can filter meetings using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|----------------------------------| | `id` | Unique identifier for Meetings | `int64` | `=` | `id=1` | | `startTime` | Start time of when Meeting was scheduled | `datetime` | `>`, `<`, `>=`, `<=` | `startTime>2025-01-01T01:00:00Z` | | `createdAt` | When the Meeting was created in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-01-01T01:00:00Z` | | `updatedAt` | When the Meeting was updated in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-01-01T01:00:00Z`| + * Get metadata on all Meetings + * @param param the request object + */ + public v2MeetingsGET(param: MeetingsApiV2MeetingsGETRequest = {}, options?: ConfigurationOptions): Promise { + return this.api.v2MeetingsGET(param.cursor, param.limit, param.filter, options).toPromise(); + } + +} + +import { ObservableNotesApi } from "./ObservableAPI.ts"; +import { NotesApiRequestFactory, NotesApiResponseProcessor} from "../apis/NotesApi.ts"; + +export interface NotesApiV2NotesGETRequest { + /** + * Include total count of the collection in the pagination response + * Defaults to: false + * @type boolean + * @memberof NotesApiv2NotesGET + */ + totalCount?: boolean + /** + * Cursor for the next or previous page + * Defaults to: undefined + * @type string + * @memberof NotesApiv2NotesGET + */ + cursor?: string + /** + * Number of items to include in the page + * Minimum: 0 + * Maximum: 100 + * Defaults to: 20 + * @type number + * @memberof NotesApiv2NotesGET + */ + limit?: number + /** + * Filter options + * Defaults to: undefined + * @type string + * @memberof NotesApiv2NotesGET + */ + filter?: string + /** + * Additional properties to include in the response + * Defaults to: undefined + * @type Set<'companiesPreview' | 'personsPreview' | 'opportunitiesPreview' | 'repliesCount'> + * @memberof NotesApiv2NotesGET + */ + includes?: Set<'companiesPreview' | 'personsPreview' | 'opportunitiesPreview' | 'repliesCount'> +} + +export interface NotesApiV2NotesNoteIdAttachedCompaniesGETRequest { + /** + * The id of the Note to get attached Companies + * Minimum: 1 + * Maximum: 2147483647 + * Defaults to: undefined + * @type number + * @memberof NotesApiv2NotesNoteIdAttachedCompaniesGET + */ + noteId: number + /** + * Include total count of the collection in the pagination response + * Defaults to: false + * @type boolean + * @memberof NotesApiv2NotesNoteIdAttachedCompaniesGET + */ + totalCount?: boolean + /** + * Cursor for the next or previous page + * Defaults to: undefined + * @type string + * @memberof NotesApiv2NotesNoteIdAttachedCompaniesGET + */ + cursor?: string + /** + * Number of items to include in the page + * Minimum: 0 + * Maximum: 100 + * Defaults to: 20 + * @type number + * @memberof NotesApiv2NotesNoteIdAttachedCompaniesGET + */ + limit?: number +} + +export interface NotesApiV2NotesNoteIdAttachedOpportunitiesGETRequest { + /** + * The id of the Note to get attached Opportunities + * Minimum: 1 + * Maximum: 2147483647 + * Defaults to: undefined + * @type number + * @memberof NotesApiv2NotesNoteIdAttachedOpportunitiesGET + */ + noteId: number + /** + * Include total count of the collection in the pagination response + * Defaults to: false + * @type boolean + * @memberof NotesApiv2NotesNoteIdAttachedOpportunitiesGET + */ + totalCount?: boolean + /** + * Cursor for the next or previous page + * Defaults to: undefined + * @type string + * @memberof NotesApiv2NotesNoteIdAttachedOpportunitiesGET + */ + cursor?: string + /** + * Number of items to include in the page + * Minimum: 0 + * Maximum: 100 + * Defaults to: 20 + * @type number + * @memberof NotesApiv2NotesNoteIdAttachedOpportunitiesGET + */ + limit?: number +} + +export interface NotesApiV2NotesNoteIdAttachedPersonsGETRequest { + /** + * The id of the Note to get attached Persons + * Minimum: 1 + * Maximum: 2147483647 + * Defaults to: undefined + * @type number + * @memberof NotesApiv2NotesNoteIdAttachedPersonsGET + */ + noteId: number + /** + * Include total count of the collection in the pagination response + * Defaults to: false + * @type boolean + * @memberof NotesApiv2NotesNoteIdAttachedPersonsGET + */ + totalCount?: boolean + /** + * Cursor for the next or previous page + * Defaults to: undefined + * @type string + * @memberof NotesApiv2NotesNoteIdAttachedPersonsGET + */ + cursor?: string + /** + * Number of items to include in the page + * Minimum: 0 + * Maximum: 100 + * Defaults to: 20 + * @type number + * @memberof NotesApiv2NotesNoteIdAttachedPersonsGET + */ + limit?: number +} + +export interface NotesApiV2NotesNoteIdGETRequest { + /** + * The id of the Note + * Minimum: 1 + * Maximum: 2147483647 + * Defaults to: undefined + * @type number + * @memberof NotesApiv2NotesNoteIdGET + */ + noteId: number + /** + * Additional properties to include in the response + * Defaults to: undefined + * @type Set<'companiesPreview' | 'personsPreview' | 'opportunitiesPreview' | 'repliesCount'> + * @memberof NotesApiv2NotesNoteIdGET + */ + includes?: Set<'companiesPreview' | 'personsPreview' | 'opportunitiesPreview' | 'repliesCount'> +} + +export interface NotesApiV2NotesNoteIdRepliesGETRequest { + /** + * Note ID + * Minimum: 1 + * Maximum: 2147483647 + * Defaults to: undefined + * @type number + * @memberof NotesApiv2NotesNoteIdRepliesGET + */ + noteId: number + /** + * Filter options + * Defaults to: undefined + * @type string + * @memberof NotesApiv2NotesNoteIdRepliesGET + */ + filter?: string + /** + * Cursor for the next or previous page + * Defaults to: undefined + * @type string + * @memberof NotesApiv2NotesNoteIdRepliesGET + */ + cursor?: string + /** + * Number of items to include in the page + * Minimum: 0 + * Maximum: 100 + * Defaults to: 20 + * @type number + * @memberof NotesApiv2NotesNoteIdRepliesGET + */ + limit?: number + /** + * Include total count of the collection in the pagination response + * Defaults to: false + * @type boolean + * @memberof NotesApiv2NotesNoteIdRepliesGET + */ + totalCount?: boolean +} + +export class ObjectNotesApi { + private api: ObservableNotesApi + + public constructor(configuration: Configuration, requestFactory?: NotesApiRequestFactory, responseProcessor?: NotesApiResponseProcessor) { + this.api = new ObservableNotesApi(configuration, requestFactory, responseProcessor); + } + + /** + * | ⚠️ This endpoint is currently in BETA | |--| Returns all notes, with the exception of replies. You can filter notes using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|---------------------------------| | `id` | Filter notes by id | `int32` | `=` | `id=1` | | `creator.id` | Filter notes by the creator of the note | `int32` | `=` | `creator.id=1` | | `createdAt` | Filter notes by when it was created | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-02-04T10:48:24Z` | | `updatedAt` | Filter notes by when it was updated | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-02-03T10:48:24Z`| + * Get all Notes * @param param the request object */ - public v2ListsListIdListEntriesGETWithHttpInfo(param: ListsApiV2ListsListIdListEntriesGETRequest, options?: ConfigurationOptions): Promise> { - return this.api.v2ListsListIdListEntriesGETWithHttpInfo(param.listId, param.cursor, param.limit, param.fieldIds, param.fieldTypes, options).toPromise(); + public v2NotesGETWithHttpInfo(param: NotesApiV2NotesGETRequest = {}, options?: ConfigurationOptions): Promise> { + return this.api.v2NotesGETWithHttpInfo(param.totalCount, param.cursor, param.limit, param.filter, param.includes, options).toPromise(); } /** - * Paginate through the List Entries (AKA rows) on a given List. Returns basic information and field data, including list-specific field data, on each Company, Person, or Opportunity on the List. List Entries also include metadata about their creation, i.e., when they were added to the List and by whom. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/lists/{listId}/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, List Entries will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Get all List Entries on a List + * | ⚠️ This endpoint is currently in BETA | |--| Returns all notes, with the exception of replies. You can filter notes using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|---------------------------------| | `id` | Filter notes by id | `int32` | `=` | `id=1` | | `creator.id` | Filter notes by the creator of the note | `int32` | `=` | `creator.id=1` | | `createdAt` | Filter notes by when it was created | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-02-04T10:48:24Z` | | `updatedAt` | Filter notes by when it was updated | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-02-03T10:48:24Z`| + * Get all Notes * @param param the request object */ - public v2ListsListIdListEntriesGET(param: ListsApiV2ListsListIdListEntriesGETRequest, options?: ConfigurationOptions): Promise { - return this.api.v2ListsListIdListEntriesGET(param.listId, param.cursor, param.limit, param.fieldIds, param.fieldTypes, options).toPromise(); + public v2NotesGET(param: NotesApiV2NotesGETRequest = {}, options?: ConfigurationOptions): Promise { + return this.api.v2NotesGET(param.totalCount, param.cursor, param.limit, param.filter, param.includes, options).toPromise(); } /** - * | ⚠️ This endpoint is currently in BETA | |--| Returns a single field value on a list entry. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Get a single field value [BETA] + * | ⚠️ This endpoint is currently in BETA | |--| Returns directly attached companies for a given Note. + * Get Companies attached to a Note * @param param the request object */ - public v2ListsListIdListEntriesListEntryIdFieldsFieldIdGETWithHttpInfo(param: ListsApiV2ListsListIdListEntriesListEntryIdFieldsFieldIdGETRequest, options?: ConfigurationOptions): Promise> { - return this.api.v2ListsListIdListEntriesListEntryIdFieldsFieldIdGETWithHttpInfo(param.listId, param.listEntryId, param.fieldId, options).toPromise(); + public v2NotesNoteIdAttachedCompaniesGETWithHttpInfo(param: NotesApiV2NotesNoteIdAttachedCompaniesGETRequest, options?: ConfigurationOptions): Promise> { + return this.api.v2NotesNoteIdAttachedCompaniesGETWithHttpInfo(param.noteId, param.totalCount, param.cursor, param.limit, options).toPromise(); } /** - * | ⚠️ This endpoint is currently in BETA | |--| Returns a single field value on a list entry. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Get a single field value [BETA] + * | ⚠️ This endpoint is currently in BETA | |--| Returns directly attached companies for a given Note. + * Get Companies attached to a Note * @param param the request object */ - public v2ListsListIdListEntriesListEntryIdFieldsFieldIdGET(param: ListsApiV2ListsListIdListEntriesListEntryIdFieldsFieldIdGETRequest, options?: ConfigurationOptions): Promise { - return this.api.v2ListsListIdListEntriesListEntryIdFieldsFieldIdGET(param.listId, param.listEntryId, param.fieldId, options).toPromise(); + public v2NotesNoteIdAttachedCompaniesGET(param: NotesApiV2NotesNoteIdAttachedCompaniesGETRequest, options?: ConfigurationOptions): Promise { + return this.api.v2NotesNoteIdAttachedCompaniesGET(param.noteId, param.totalCount, param.cursor, param.limit, options).toPromise(); } /** - * | ⚠️ This endpoint is currently in BETA | |--| Update a single field value. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Update a single field value on a List Entry [BETA] + * | ⚠️ This endpoint is currently in BETA | |--| Returns directly attached opportunities for a given Note. + * Get Opportunities attached to a Note * @param param the request object */ - public v2ListsListIdListEntriesListEntryIdFieldsFieldIdPOSTWithHttpInfo(param: ListsApiV2ListsListIdListEntriesListEntryIdFieldsFieldIdPOSTRequest, options?: ConfigurationOptions): Promise> { - return this.api.v2ListsListIdListEntriesListEntryIdFieldsFieldIdPOSTWithHttpInfo(param.listId, param.listEntryId, param.fieldId, param.fieldUpdate, options).toPromise(); + public v2NotesNoteIdAttachedOpportunitiesGETWithHttpInfo(param: NotesApiV2NotesNoteIdAttachedOpportunitiesGETRequest, options?: ConfigurationOptions): Promise> { + return this.api.v2NotesNoteIdAttachedOpportunitiesGETWithHttpInfo(param.noteId, param.totalCount, param.cursor, param.limit, options).toPromise(); } /** - * | ⚠️ This endpoint is currently in BETA | |--| Update a single field value. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Update a single field value on a List Entry [BETA] + * | ⚠️ This endpoint is currently in BETA | |--| Returns directly attached opportunities for a given Note. + * Get Opportunities attached to a Note * @param param the request object */ - public v2ListsListIdListEntriesListEntryIdFieldsFieldIdPOST(param: ListsApiV2ListsListIdListEntriesListEntryIdFieldsFieldIdPOSTRequest, options?: ConfigurationOptions): Promise { - return this.api.v2ListsListIdListEntriesListEntryIdFieldsFieldIdPOST(param.listId, param.listEntryId, param.fieldId, param.fieldUpdate, options).toPromise(); + public v2NotesNoteIdAttachedOpportunitiesGET(param: NotesApiV2NotesNoteIdAttachedOpportunitiesGETRequest, options?: ConfigurationOptions): Promise { + return this.api.v2NotesNoteIdAttachedOpportunitiesGET(param.noteId, param.totalCount, param.cursor, param.limit, options).toPromise(); } /** - * | ⚠️ This endpoint is currently in BETA | |--| Paginate through all field values on a single list entry. All fields will be included by default. The `ids` and `types` parameters can be used to filter the collection. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Get field values on a single List Entry [BETA] + * | ⚠️ This endpoint is currently in BETA | |--| Returns directly attached persons for a given Note. + * Get Persons attached to a Note * @param param the request object */ - public v2ListsListIdListEntriesListEntryIdFieldsGETWithHttpInfo(param: ListsApiV2ListsListIdListEntriesListEntryIdFieldsGETRequest, options?: ConfigurationOptions): Promise> { - return this.api.v2ListsListIdListEntriesListEntryIdFieldsGETWithHttpInfo(param.listId, param.listEntryId, param.ids, param.types, param.cursor, param.limit, options).toPromise(); + public v2NotesNoteIdAttachedPersonsGETWithHttpInfo(param: NotesApiV2NotesNoteIdAttachedPersonsGETRequest, options?: ConfigurationOptions): Promise> { + return this.api.v2NotesNoteIdAttachedPersonsGETWithHttpInfo(param.noteId, param.totalCount, param.cursor, param.limit, options).toPromise(); } /** - * | ⚠️ This endpoint is currently in BETA | |--| Paginate through all field values on a single list entry. All fields will be included by default. The `ids` and `types` parameters can be used to filter the collection. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Get field values on a single List Entry [BETA] + * | ⚠️ This endpoint is currently in BETA | |--| Returns directly attached persons for a given Note. + * Get Persons attached to a Note * @param param the request object */ - public v2ListsListIdListEntriesListEntryIdFieldsGET(param: ListsApiV2ListsListIdListEntriesListEntryIdFieldsGETRequest, options?: ConfigurationOptions): Promise { - return this.api.v2ListsListIdListEntriesListEntryIdFieldsGET(param.listId, param.listEntryId, param.ids, param.types, param.cursor, param.limit, options).toPromise(); + public v2NotesNoteIdAttachedPersonsGET(param: NotesApiV2NotesNoteIdAttachedPersonsGETRequest, options?: ConfigurationOptions): Promise { + return this.api.v2NotesNoteIdAttachedPersonsGET(param.noteId, param.totalCount, param.cursor, param.limit, options).toPromise(); } /** - * | ⚠️ This endpoint is currently in BETA | |--| Perform batch operations on a list entry\'s fields. Currently the only operation at the endpoint is `update-fields`, which allows you to update multiple field values with a single request. This is equivalent to calling [the single field update](#operation/v2_lists_listId_list-entries_listEntryId_fields_fieldId__POST) endpoint multiple times. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Perform batch operations on a list entry\'s fields [BETA] + * | ⚠️ This endpoint is currently in BETA | |--| Get a Note with a given id + * Get a single Note * @param param the request object */ - public v2ListsListIdListEntriesListEntryIdFieldsPATCHWithHttpInfo(param: ListsApiV2ListsListIdListEntriesListEntryIdFieldsPATCHRequest, options?: ConfigurationOptions): Promise> { - return this.api.v2ListsListIdListEntriesListEntryIdFieldsPATCHWithHttpInfo(param.listId, param.listEntryId, param.body, options).toPromise(); + public v2NotesNoteIdGETWithHttpInfo(param: NotesApiV2NotesNoteIdGETRequest, options?: ConfigurationOptions): Promise> { + return this.api.v2NotesNoteIdGETWithHttpInfo(param.noteId, param.includes, options).toPromise(); } /** - * | ⚠️ This endpoint is currently in BETA | |--| Perform batch operations on a list entry\'s fields. Currently the only operation at the endpoint is `update-fields`, which allows you to update multiple field values with a single request. This is equivalent to calling [the single field update](#operation/v2_lists_listId_list-entries_listEntryId_fields_fieldId__POST) endpoint multiple times. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Perform batch operations on a list entry\'s fields [BETA] + * | ⚠️ This endpoint is currently in BETA | |--| Get a Note with a given id + * Get a single Note * @param param the request object */ - public v2ListsListIdListEntriesListEntryIdFieldsPATCH(param: ListsApiV2ListsListIdListEntriesListEntryIdFieldsPATCHRequest, options?: ConfigurationOptions): Promise { - return this.api.v2ListsListIdListEntriesListEntryIdFieldsPATCH(param.listId, param.listEntryId, param.body, options).toPromise(); + public v2NotesNoteIdGET(param: NotesApiV2NotesNoteIdGETRequest, options?: ConfigurationOptions): Promise { + return this.api.v2NotesNoteIdGET(param.noteId, param.includes, options).toPromise(); } /** - * | ⚠️ This endpoint is currently in BETA | |--| Retrieve a single list entry. Returns basic information and field data, including list-specific field data. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/lists/{listId}/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, the List Entry will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Get a single List Entry on a List [BETA] + * | ⚠️ This endpoint is currently in BETA | |--| This endpoint returns reply notes for a given note id. You can filter replies using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|---------------------------------| | `creator.id` | Filter notes by the creator of the note | `int32` | `=` | `creator.id=1` | | `createdAt` | Filter notes by when it was created | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-02-04T10:48:24Z` | | `updatedAt` | Filter notes by when it was updated | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-02-03T10:48:24Z`| + * Get replies for a Note * @param param the request object */ - public v2ListsListIdListEntriesListEntryIdGETWithHttpInfo(param: ListsApiV2ListsListIdListEntriesListEntryIdGETRequest, options?: ConfigurationOptions): Promise> { - return this.api.v2ListsListIdListEntriesListEntryIdGETWithHttpInfo(param.listId, param.listEntryId, param.fieldIds, param.fieldTypes, options).toPromise(); + public v2NotesNoteIdRepliesGETWithHttpInfo(param: NotesApiV2NotesNoteIdRepliesGETRequest, options?: ConfigurationOptions): Promise> { + return this.api.v2NotesNoteIdRepliesGETWithHttpInfo(param.noteId, param.filter, param.cursor, param.limit, param.totalCount, options).toPromise(); } /** - * | ⚠️ This endpoint is currently in BETA | |--| Retrieve a single list entry. Returns basic information and field data, including list-specific field data. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/lists/{listId}/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, the List Entry will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Get a single List Entry on a List [BETA] + * | ⚠️ This endpoint is currently in BETA | |--| This endpoint returns reply notes for a given note id. You can filter replies using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|---------------------------------| | `creator.id` | Filter notes by the creator of the note | `int32` | `=` | `creator.id=1` | | `createdAt` | Filter notes by when it was created | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-02-04T10:48:24Z` | | `updatedAt` | Filter notes by when it was updated | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-02-03T10:48:24Z`| + * Get replies for a Note * @param param the request object */ - public v2ListsListIdListEntriesListEntryIdGET(param: ListsApiV2ListsListIdListEntriesListEntryIdGETRequest, options?: ConfigurationOptions): Promise { - return this.api.v2ListsListIdListEntriesListEntryIdGET(param.listId, param.listEntryId, param.fieldIds, param.fieldTypes, options).toPromise(); + public v2NotesNoteIdRepliesGET(param: NotesApiV2NotesNoteIdRepliesGETRequest, options?: ConfigurationOptions): Promise { + return this.api.v2NotesNoteIdRepliesGET(param.noteId, param.filter, param.cursor, param.limit, param.totalCount, options).toPromise(); } } @@ -966,12 +1811,12 @@ export class ObjectListsApi { import { ObservableOpportunitiesApi } from "./ObservableAPI.ts"; import { OpportunitiesApiRequestFactory, OpportunitiesApiResponseProcessor} from "../apis/OpportunitiesApi.ts"; -export interface OpportunitiesApiGetV2OpportunitiesRequest { +export interface OpportunitiesApiV2OpportunitiesGETRequest { /** * Cursor for the next or previous page * Defaults to: undefined * @type string - * @memberof OpportunitiesApigetV2Opportunities + * @memberof OpportunitiesApiv2OpportunitiesGET */ cursor?: string /** @@ -980,28 +1825,70 @@ export interface OpportunitiesApiGetV2OpportunitiesRequest { * Maximum: 100 * Defaults to: 100 * @type number - * @memberof OpportunitiesApigetV2Opportunities + * @memberof OpportunitiesApiv2OpportunitiesGET */ limit?: number /** * Opportunity IDs * Defaults to: undefined * @type Array<number> - * @memberof OpportunitiesApigetV2Opportunities + * @memberof OpportunitiesApiv2OpportunitiesGET */ ids?: Array } -export interface OpportunitiesApiGetV2OpportunitiesIdRequest { +export interface OpportunitiesApiV2OpportunitiesOpportunityIdGETRequest { + /** + * Opportunity ID + * Minimum: 1 + * Maximum: 9223372036854776000 + * Defaults to: undefined + * @type number + * @memberof OpportunitiesApiv2OpportunitiesOpportunityIdGET + */ + opportunityId: number +} + +export interface OpportunitiesApiV2OpportunitiesOpportunityIdNotesGETRequest { /** * Opportunity ID * Minimum: 1 - * Maximum: -9223372036854775616 + * Maximum: 9223372036854776000 + * Defaults to: undefined + * @type number + * @memberof OpportunitiesApiv2OpportunitiesOpportunityIdNotesGET + */ + opportunityId: number + /** + * Filter options + * Defaults to: undefined + * @type string + * @memberof OpportunitiesApiv2OpportunitiesOpportunityIdNotesGET + */ + filter?: string + /** + * Cursor for the next or previous page * Defaults to: undefined + * @type string + * @memberof OpportunitiesApiv2OpportunitiesOpportunityIdNotesGET + */ + cursor?: string + /** + * Number of items to include in the page + * Minimum: 0 + * Maximum: 100 + * Defaults to: 20 * @type number - * @memberof OpportunitiesApigetV2OpportunitiesId + * @memberof OpportunitiesApiv2OpportunitiesOpportunityIdNotesGET + */ + limit?: number + /** + * Include total count of the collection in the pagination response + * Defaults to: false + * @type boolean + * @memberof OpportunitiesApiv2OpportunitiesOpportunityIdNotesGET */ - id: number + totalCount?: boolean } export class ObjectOpportunitiesApi { @@ -1016,8 +1903,8 @@ export class ObjectOpportunitiesApi { * Get all Opportunities * @param param the request object */ - public getV2OpportunitiesWithHttpInfo(param: OpportunitiesApiGetV2OpportunitiesRequest = {}, options?: ConfigurationOptions): Promise> { - return this.api.getV2OpportunitiesWithHttpInfo(param.cursor, param.limit, param.ids, options).toPromise(); + public v2OpportunitiesGETWithHttpInfo(param: OpportunitiesApiV2OpportunitiesGETRequest = {}, options?: ConfigurationOptions): Promise> { + return this.api.v2OpportunitiesGETWithHttpInfo(param.cursor, param.limit, param.ids, options).toPromise(); } /** @@ -1025,8 +1912,8 @@ export class ObjectOpportunitiesApi { * Get all Opportunities * @param param the request object */ - public getV2Opportunities(param: OpportunitiesApiGetV2OpportunitiesRequest = {}, options?: ConfigurationOptions): Promise { - return this.api.getV2Opportunities(param.cursor, param.limit, param.ids, options).toPromise(); + public v2OpportunitiesGET(param: OpportunitiesApiV2OpportunitiesGETRequest = {}, options?: ConfigurationOptions): Promise { + return this.api.v2OpportunitiesGET(param.cursor, param.limit, param.ids, options).toPromise(); } /** @@ -1034,8 +1921,8 @@ export class ObjectOpportunitiesApi { * Get a single Opportunity * @param param the request object */ - public getV2OpportunitiesIdWithHttpInfo(param: OpportunitiesApiGetV2OpportunitiesIdRequest, options?: ConfigurationOptions): Promise> { - return this.api.getV2OpportunitiesIdWithHttpInfo(param.id, options).toPromise(); + public v2OpportunitiesOpportunityIdGETWithHttpInfo(param: OpportunitiesApiV2OpportunitiesOpportunityIdGETRequest, options?: ConfigurationOptions): Promise> { + return this.api.v2OpportunitiesOpportunityIdGETWithHttpInfo(param.opportunityId, options).toPromise(); } /** @@ -1043,61 +1930,243 @@ export class ObjectOpportunitiesApi { * Get a single Opportunity * @param param the request object */ - public getV2OpportunitiesId(param: OpportunitiesApiGetV2OpportunitiesIdRequest, options?: ConfigurationOptions): Promise { - return this.api.getV2OpportunitiesId(param.id, options).toPromise(); + public v2OpportunitiesOpportunityIdGET(param: OpportunitiesApiV2OpportunitiesOpportunityIdGETRequest, options?: ConfigurationOptions): Promise { + return this.api.v2OpportunitiesOpportunityIdGET(param.opportunityId, options).toPromise(); + } + + /** + * | ⚠️ This endpoint is currently in BETA | |--| Returns Notes for a given Opportunity which includes directly attached notes and those attached to persons on this Opportunity. You can filter notes using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|---------------------------------| | `creator.id` | Filter notes by the creator of the note | `int32` | `=` | `creator.id=1` | | `createdAt` | Filter notes by when it was created | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-02-04T10:48:24Z` | | `updatedAt` | Filter notes by when it was updated | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-02-03T10:48:24Z`| + * Get Notes for an Opportunity + * @param param the request object + */ + public v2OpportunitiesOpportunityIdNotesGETWithHttpInfo(param: OpportunitiesApiV2OpportunitiesOpportunityIdNotesGETRequest, options?: ConfigurationOptions): Promise> { + return this.api.v2OpportunitiesOpportunityIdNotesGETWithHttpInfo(param.opportunityId, param.filter, param.cursor, param.limit, param.totalCount, options).toPromise(); + } + + /** + * | ⚠️ This endpoint is currently in BETA | |--| Returns Notes for a given Opportunity which includes directly attached notes and those attached to persons on this Opportunity. You can filter notes using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|---------------------------------| | `creator.id` | Filter notes by the creator of the note | `int32` | `=` | `creator.id=1` | | `createdAt` | Filter notes by when it was created | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-02-04T10:48:24Z` | | `updatedAt` | Filter notes by when it was updated | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-02-03T10:48:24Z`| + * Get Notes for an Opportunity + * @param param the request object + */ + public v2OpportunitiesOpportunityIdNotesGET(param: OpportunitiesApiV2OpportunitiesOpportunityIdNotesGETRequest, options?: ConfigurationOptions): Promise { + return this.api.v2OpportunitiesOpportunityIdNotesGET(param.opportunityId, param.filter, param.cursor, param.limit, param.totalCount, options).toPromise(); } } -import { ObservablePersonsApi } from "./ObservableAPI.ts"; -import { PersonsApiRequestFactory, PersonsApiResponseProcessor} from "../apis/PersonsApi.ts"; +import { ObservablePersonMergesApi } from "./ObservableAPI.ts"; +import { PersonMergesApiRequestFactory, PersonMergesApiResponseProcessor} from "../apis/PersonMergesApi.ts"; -export interface PersonsApiGetV2PersonsRequest { +export interface PersonMergesApiV2PersonMergesGETRequest { /** * Cursor for the next or previous page * Defaults to: undefined * @type string - * @memberof PersonsApigetV2Persons + * @memberof PersonMergesApiv2PersonMergesGET */ cursor?: string /** * Number of items to include in the page * Minimum: 1 * Maximum: 100 - * Defaults to: 100 + * Defaults to: 25 * @type number - * @memberof PersonsApigetV2Persons + * @memberof PersonMergesApiv2PersonMergesGET */ limit?: number /** - * People IDs + * Filter person merges using Affinity Filtering Language * Defaults to: undefined - * @type Array<number> - * @memberof PersonsApigetV2Persons + * @type string + * @memberof PersonMergesApiv2PersonMergesGET */ - ids?: Array + filter?: string +} + +export interface PersonMergesApiV2PersonMergesMergeIdGETRequest { /** - * Field IDs for which to return field data + * Person merge ID + * Minimum: 1 + * Maximum: 9007199254740991 * Defaults to: undefined - * @type Array<string> - * @memberof PersonsApigetV2Persons + * @type number + * @memberof PersonMergesApiv2PersonMergesMergeIdGET */ - fieldIds?: Array + mergeId: number +} + +export interface PersonMergesApiV2PersonMergesPOSTRequest { /** - * Field Types for which to return field data + * + * @type PersonMergeRequest + * @memberof PersonMergesApiv2PersonMergesPOST + */ + personMergeRequest: PersonMergeRequest +} + +export interface PersonMergesApiV2TasksPersonMergesGETRequest { + /** + * Cursor for the next or previous page * Defaults to: undefined - * @type Array<'enriched' | 'global' | 'relationship-intelligence'> - * @memberof PersonsApigetV2Persons + * @type string + * @memberof PersonMergesApiv2TasksPersonMergesGET */ - fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'> + cursor?: string + /** + * Number of items to include in the page + * Minimum: 1 + * Maximum: 100 + * Defaults to: 25 + * @type number + * @memberof PersonMergesApiv2TasksPersonMergesGET + */ + limit?: number + /** + * Filter tasks using Affinity Filtering Language + * Defaults to: undefined + * @type string + * @memberof PersonMergesApiv2TasksPersonMergesGET + */ + filter?: string +} + +export interface PersonMergesApiV2TasksPersonMergesTaskIdGETRequest { + /** + * Person merge task ID + * Defaults to: undefined + * @type string + * @memberof PersonMergesApiv2TasksPersonMergesTaskIdGET + */ + taskId: string +} + +export class ObjectPersonMergesApi { + private api: ObservablePersonMergesApi + + public constructor(configuration: Configuration, requestFactory?: PersonMergesApiRequestFactory, responseProcessor?: PersonMergesApiResponseProcessor) { + this.api = new ObservablePersonMergesApi(configuration, requestFactory, responseProcessor); + } + + /** + * Retrieve paginated person merges for the organization. Returns all person merges initiated by users in your organization, including their current status, the persons involved, and merge details. You can filter person merges using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties: | Property | Type | Operators | Values | Examples | |----------|------|-----------|--------|----------| | `status` | `enum` | `=` | `in-progress`, `success`, `failed` | `status=failed` | | `taskId` | `string` | `=` | | `taskId=789e0123-e45b-67c8-d901-234567890123` | Person merges are returned in reverse chronological order (most recent first). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get All Person Merges + * @param param the request object + */ + public v2PersonMergesGETWithHttpInfo(param: PersonMergesApiV2PersonMergesGETRequest = {}, options?: ConfigurationOptions): Promise> { + return this.api.v2PersonMergesGETWithHttpInfo(param.cursor, param.limit, param.filter, options).toPromise(); + } + + /** + * Retrieve paginated person merges for the organization. Returns all person merges initiated by users in your organization, including their current status, the persons involved, and merge details. You can filter person merges using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties: | Property | Type | Operators | Values | Examples | |----------|------|-----------|--------|----------| | `status` | `enum` | `=` | `in-progress`, `success`, `failed` | `status=failed` | | `taskId` | `string` | `=` | | `taskId=789e0123-e45b-67c8-d901-234567890123` | Person merges are returned in reverse chronological order (most recent first). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get All Person Merges + * @param param the request object + */ + public v2PersonMergesGET(param: PersonMergesApiV2PersonMergesGETRequest = {}, options?: ConfigurationOptions): Promise { + return this.api.v2PersonMergesGET(param.cursor, param.limit, param.filter, options).toPromise(); + } + + /** + * Retrieve the status and details of a specific person merge. Returns information about the person merge including its current status, the persons involved, timestamps, and any error information if the merge failed. The `mergeId` can be obtained from the response of the [Get All Person Merges](#tag/personMerges/operation/v2_person-merges__GET) endpoint, or by filtering person merges by task ID using `/v2/person-merges?filter=taskId={taskId}` after initiating a merge. Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get Person Merge + * @param param the request object + */ + public v2PersonMergesMergeIdGETWithHttpInfo(param: PersonMergesApiV2PersonMergesMergeIdGETRequest, options?: ConfigurationOptions): Promise> { + return this.api.v2PersonMergesMergeIdGETWithHttpInfo(param.mergeId, options).toPromise(); + } + + /** + * Retrieve the status and details of a specific person merge. Returns information about the person merge including its current status, the persons involved, timestamps, and any error information if the merge failed. The `mergeId` can be obtained from the response of the [Get All Person Merges](#tag/personMerges/operation/v2_person-merges__GET) endpoint, or by filtering person merges by task ID using `/v2/person-merges?filter=taskId={taskId}` after initiating a merge. Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get Person Merge + * @param param the request object + */ + public v2PersonMergesMergeIdGET(param: PersonMergesApiV2PersonMergesMergeIdGETRequest, options?: ConfigurationOptions): Promise { + return this.api.v2PersonMergesMergeIdGET(param.mergeId, options).toPromise(); + } + + /** + * Initiate a person merge to combine a duplicate person profile into a primary person profile. This is an asynchronous process that will merge all data from the duplicate person into the primary person. Once the merge is initiated, you can track its progress using the returned [task URL](#tag/personMerges/operation/v2_tasks_person-merges_taskId__GET). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Initiate Person Merge + * @param param the request object + */ + public v2PersonMergesPOSTWithHttpInfo(param: PersonMergesApiV2PersonMergesPOSTRequest, options?: ConfigurationOptions): Promise> { + return this.api.v2PersonMergesPOSTWithHttpInfo(param.personMergeRequest, options).toPromise(); + } + + /** + * Initiate a person merge to combine a duplicate person profile into a primary person profile. This is an asynchronous process that will merge all data from the duplicate person into the primary person. Once the merge is initiated, you can track its progress using the returned [task URL](#tag/personMerges/operation/v2_tasks_person-merges_taskId__GET). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Initiate Person Merge + * @param param the request object + */ + public v2PersonMergesPOST(param: PersonMergesApiV2PersonMergesPOSTRequest, options?: ConfigurationOptions): Promise { + return this.api.v2PersonMergesPOST(param.personMergeRequest, options).toPromise(); + } + + /** + * Retrieve paginated person merge tasks for the organization. Returns all merge tasks initiated by users in your organization, including their current status, the persons involved, and task details. You can filter tasks using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties: | Property | Type | Operators | Values | Examples | |----------|------|-----------|--------|----------| | `status` | `enum` | `=` | `in-progress`, `success`, `failed` | `status=failed` | Tasks are returned in reverse chronological order (most recent first). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get All Person Merge Tasks + * @param param the request object + */ + public v2TasksPersonMergesGETWithHttpInfo(param: PersonMergesApiV2TasksPersonMergesGETRequest = {}, options?: ConfigurationOptions): Promise> { + return this.api.v2TasksPersonMergesGETWithHttpInfo(param.cursor, param.limit, param.filter, options).toPromise(); + } + + /** + * Retrieve paginated person merge tasks for the organization. Returns all merge tasks initiated by users in your organization, including their current status, the persons involved, and task details. You can filter tasks using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties: | Property | Type | Operators | Values | Examples | |----------|------|-----------|--------|----------| | `status` | `enum` | `=` | `in-progress`, `success`, `failed` | `status=failed` | Tasks are returned in reverse chronological order (most recent first). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get All Person Merge Tasks + * @param param the request object + */ + public v2TasksPersonMergesGET(param: PersonMergesApiV2TasksPersonMergesGETRequest = {}, options?: ConfigurationOptions): Promise { + return this.api.v2TasksPersonMergesGET(param.cursor, param.limit, param.filter, options).toPromise(); + } + + /** + * Retrieve the status and details of a specific task for person merges. Returns information about the person merges for a specific task including its overall status, number of merges in-progress, completed, and failed. Detailed information about individual merges for this task can be found by querying: `/v2/person-merges?filter=taskId={taskId}` See [Person Merges](#tag/personMerges/operation/v2_person-merges__GET) for more details. Task statuses: - `in-progress`: The merge task is currently being processed. - `success`: The merge task completed successfully. - `failed`: The merge task failed. Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get Person Merge Task + * @param param the request object + */ + public v2TasksPersonMergesTaskIdGETWithHttpInfo(param: PersonMergesApiV2TasksPersonMergesTaskIdGETRequest, options?: ConfigurationOptions): Promise> { + return this.api.v2TasksPersonMergesTaskIdGETWithHttpInfo(param.taskId, options).toPromise(); + } + + /** + * Retrieve the status and details of a specific task for person merges. Returns information about the person merges for a specific task including its overall status, number of merges in-progress, completed, and failed. Detailed information about individual merges for this task can be found by querying: `/v2/person-merges?filter=taskId={taskId}` See [Person Merges](#tag/personMerges/operation/v2_person-merges__GET) for more details. Task statuses: - `in-progress`: The merge task is currently being processed. - `success`: The merge task completed successfully. - `failed`: The merge task failed. Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get Person Merge Task + * @param param the request object + */ + public v2TasksPersonMergesTaskIdGET(param: PersonMergesApiV2TasksPersonMergesTaskIdGETRequest, options?: ConfigurationOptions): Promise { + return this.api.v2TasksPersonMergesTaskIdGET(param.taskId, options).toPromise(); + } + +} + +import { ObservablePersonsApi } from "./ObservableAPI.ts"; +import { PersonsApiRequestFactory, PersonsApiResponseProcessor} from "../apis/PersonsApi.ts"; + +export interface PersonsApiV2PersonsFieldsGETRequest { + /** + * Cursor for the next or previous page + * Defaults to: undefined + * @type string + * @memberof PersonsApiv2PersonsFieldsGET + */ + cursor?: string + /** + * Number of items to include in the page + * Minimum: 1 + * Maximum: 100 + * Defaults to: 100 + * @type number + * @memberof PersonsApiv2PersonsFieldsGET + */ + limit?: number } -export interface PersonsApiGetV2PersonsFieldsRequest { +export interface PersonsApiV2PersonsGETRequest { /** * Cursor for the next or previous page * Defaults to: undefined * @type string - * @memberof PersonsApigetV2PersonsFields + * @memberof PersonsApiv2PersonsGET */ cursor?: string /** @@ -1106,52 +2175,73 @@ export interface PersonsApiGetV2PersonsFieldsRequest { * Maximum: 100 * Defaults to: 100 * @type number - * @memberof PersonsApigetV2PersonsFields + * @memberof PersonsApiv2PersonsGET */ limit?: number + /** + * People IDs + * Defaults to: undefined + * @type Array<number> + * @memberof PersonsApiv2PersonsGET + */ + ids?: Array + /** + * Field IDs for which to return field data + * Defaults to: undefined + * @type Array<string> + * @memberof PersonsApiv2PersonsGET + */ + fieldIds?: Array + /** + * Field Types for which to return field data + * Defaults to: undefined + * @type Array<'enriched' | 'global' | 'relationship-intelligence'> + * @memberof PersonsApiv2PersonsGET + */ + fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'> } -export interface PersonsApiGetV2PersonsIdRequest { +export interface PersonsApiV2PersonsPersonIdGETRequest { /** * Person ID * Minimum: 1 - * Maximum: -9223372036854775616 + * Maximum: 9223372036854776000 * Defaults to: undefined * @type number - * @memberof PersonsApigetV2PersonsId + * @memberof PersonsApiv2PersonsPersonIdGET */ - id: number + personId: number /** * Field IDs for which to return field data * Defaults to: undefined * @type Array<string> - * @memberof PersonsApigetV2PersonsId + * @memberof PersonsApiv2PersonsPersonIdGET */ fieldIds?: Array /** * Field Types for which to return field data * Defaults to: undefined * @type Array<'enriched' | 'global' | 'relationship-intelligence'> - * @memberof PersonsApigetV2PersonsId + * @memberof PersonsApiv2PersonsPersonIdGET */ fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'> } -export interface PersonsApiGetV2PersonsIdListEntriesRequest { +export interface PersonsApiV2PersonsPersonIdListEntriesGETRequest { /** * Persons ID * Minimum: 1 - * Maximum: -9223372036854775616 + * Maximum: 9223372036854776000 * Defaults to: undefined * @type number - * @memberof PersonsApigetV2PersonsIdListEntries + * @memberof PersonsApiv2PersonsPersonIdListEntriesGET */ - id: number + personId: number /** * Cursor for the next or previous page * Defaults to: undefined * @type string - * @memberof PersonsApigetV2PersonsIdListEntries + * @memberof PersonsApiv2PersonsPersonIdListEntriesGET */ cursor?: string /** @@ -1160,26 +2250,26 @@ export interface PersonsApiGetV2PersonsIdListEntriesRequest { * Maximum: 100 * Defaults to: 100 * @type number - * @memberof PersonsApigetV2PersonsIdListEntries + * @memberof PersonsApiv2PersonsPersonIdListEntriesGET */ limit?: number } -export interface PersonsApiGetV2PersonsIdListsRequest { +export interface PersonsApiV2PersonsPersonIdListsGETRequest { /** * Persons ID * Minimum: 1 - * Maximum: -9223372036854775616 + * Maximum: 9223372036854776000 * Defaults to: undefined * @type number - * @memberof PersonsApigetV2PersonsIdLists + * @memberof PersonsApiv2PersonsPersonIdListsGET */ - id: number + personId: number /** * Cursor for the next or previous page * Defaults to: undefined * @type string - * @memberof PersonsApigetV2PersonsIdLists + * @memberof PersonsApiv2PersonsPersonIdListsGET */ cursor?: string /** @@ -1188,9 +2278,51 @@ export interface PersonsApiGetV2PersonsIdListsRequest { * Maximum: 100 * Defaults to: 100 * @type number - * @memberof PersonsApigetV2PersonsIdLists + * @memberof PersonsApiv2PersonsPersonIdListsGET + */ + limit?: number +} + +export interface PersonsApiV2PersonsPersonIdNotesGETRequest { + /** + * Persons ID + * Minimum: 1 + * Maximum: 9223372036854776000 + * Defaults to: undefined + * @type number + * @memberof PersonsApiv2PersonsPersonIdNotesGET + */ + personId: number + /** + * Filter options + * Defaults to: undefined + * @type string + * @memberof PersonsApiv2PersonsPersonIdNotesGET + */ + filter?: string + /** + * Cursor for the next or previous page + * Defaults to: undefined + * @type string + * @memberof PersonsApiv2PersonsPersonIdNotesGET + */ + cursor?: string + /** + * Number of items to include in the page + * Minimum: 0 + * Maximum: 100 + * Defaults to: 20 + * @type number + * @memberof PersonsApiv2PersonsPersonIdNotesGET */ limit?: number + /** + * Include total count of the collection in the pagination response + * Defaults to: false + * @type boolean + * @memberof PersonsApiv2PersonsPersonIdNotesGET + */ + totalCount?: boolean } export class ObjectPersonsApi { @@ -1201,39 +2333,39 @@ export class ObjectPersonsApi { } /** - * Paginate through Persons in Affinity. Returns basic information and non-list-specific field data on each Person. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/persons/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Persons will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All People directory\" [permission](#section/Getting-Started/Permissions). - * Get all Persons + * Returns metadata on non-list-specific Person Fields. Use the returned Field IDs to request field data from the GET `/v2/persons` and GET `/v2/persons/{id}` endpoints. + * Get metadata on Person Fields * @param param the request object */ - public getV2PersonsWithHttpInfo(param: PersonsApiGetV2PersonsRequest = {}, options?: ConfigurationOptions): Promise> { - return this.api.getV2PersonsWithHttpInfo(param.cursor, param.limit, param.ids, param.fieldIds, param.fieldTypes, options).toPromise(); + public v2PersonsFieldsGETWithHttpInfo(param: PersonsApiV2PersonsFieldsGETRequest = {}, options?: ConfigurationOptions): Promise> { + return this.api.v2PersonsFieldsGETWithHttpInfo(param.cursor, param.limit, options).toPromise(); } /** - * Paginate through Persons in Affinity. Returns basic information and non-list-specific field data on each Person. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/persons/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Persons will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All People directory\" [permission](#section/Getting-Started/Permissions). - * Get all Persons + * Returns metadata on non-list-specific Person Fields. Use the returned Field IDs to request field data from the GET `/v2/persons` and GET `/v2/persons/{id}` endpoints. + * Get metadata on Person Fields * @param param the request object */ - public getV2Persons(param: PersonsApiGetV2PersonsRequest = {}, options?: ConfigurationOptions): Promise { - return this.api.getV2Persons(param.cursor, param.limit, param.ids, param.fieldIds, param.fieldTypes, options).toPromise(); + public v2PersonsFieldsGET(param: PersonsApiV2PersonsFieldsGETRequest = {}, options?: ConfigurationOptions): Promise { + return this.api.v2PersonsFieldsGET(param.cursor, param.limit, options).toPromise(); } /** - * Returns metadata on non-list-specific Person Fields. Use the returned Field IDs to request field data from the GET `/v2/persons` and GET `/v2/persons/{id}` endpoints. - * Get metadata on Person Fields + * Paginate through Persons in Affinity. Returns basic information and non-list-specific field data on each Person. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/persons/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Persons will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All People directory\" [permission](#section/Getting-Started/Permissions). + * Get all Persons * @param param the request object */ - public getV2PersonsFieldsWithHttpInfo(param: PersonsApiGetV2PersonsFieldsRequest = {}, options?: ConfigurationOptions): Promise> { - return this.api.getV2PersonsFieldsWithHttpInfo(param.cursor, param.limit, options).toPromise(); + public v2PersonsGETWithHttpInfo(param: PersonsApiV2PersonsGETRequest = {}, options?: ConfigurationOptions): Promise> { + return this.api.v2PersonsGETWithHttpInfo(param.cursor, param.limit, param.ids, param.fieldIds, param.fieldTypes, options).toPromise(); } /** - * Returns metadata on non-list-specific Person Fields. Use the returned Field IDs to request field data from the GET `/v2/persons` and GET `/v2/persons/{id}` endpoints. - * Get metadata on Person Fields + * Paginate through Persons in Affinity. Returns basic information and non-list-specific field data on each Person. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/persons/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Persons will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All People directory\" [permission](#section/Getting-Started/Permissions). + * Get all Persons * @param param the request object */ - public getV2PersonsFields(param: PersonsApiGetV2PersonsFieldsRequest = {}, options?: ConfigurationOptions): Promise { - return this.api.getV2PersonsFields(param.cursor, param.limit, options).toPromise(); + public v2PersonsGET(param: PersonsApiV2PersonsGETRequest = {}, options?: ConfigurationOptions): Promise { + return this.api.v2PersonsGET(param.cursor, param.limit, param.ids, param.fieldIds, param.fieldTypes, options).toPromise(); } /** @@ -1241,8 +2373,8 @@ export class ObjectPersonsApi { * Get a single Person * @param param the request object */ - public getV2PersonsIdWithHttpInfo(param: PersonsApiGetV2PersonsIdRequest, options?: ConfigurationOptions): Promise> { - return this.api.getV2PersonsIdWithHttpInfo(param.id, param.fieldIds, param.fieldTypes, options).toPromise(); + public v2PersonsPersonIdGETWithHttpInfo(param: PersonsApiV2PersonsPersonIdGETRequest, options?: ConfigurationOptions): Promise> { + return this.api.v2PersonsPersonIdGETWithHttpInfo(param.personId, param.fieldIds, param.fieldTypes, options).toPromise(); } /** @@ -1250,8 +2382,8 @@ export class ObjectPersonsApi { * Get a single Person * @param param the request object */ - public getV2PersonsId(param: PersonsApiGetV2PersonsIdRequest, options?: ConfigurationOptions): Promise { - return this.api.getV2PersonsId(param.id, param.fieldIds, param.fieldTypes, options).toPromise(); + public v2PersonsPersonIdGET(param: PersonsApiV2PersonsPersonIdGETRequest, options?: ConfigurationOptions): Promise { + return this.api.v2PersonsPersonIdGET(param.personId, param.fieldIds, param.fieldTypes, options).toPromise(); } /** @@ -1259,8 +2391,8 @@ export class ObjectPersonsApi { * Get a Person\'s List Entries * @param param the request object */ - public getV2PersonsIdListEntriesWithHttpInfo(param: PersonsApiGetV2PersonsIdListEntriesRequest, options?: ConfigurationOptions): Promise> { - return this.api.getV2PersonsIdListEntriesWithHttpInfo(param.id, param.cursor, param.limit, options).toPromise(); + public v2PersonsPersonIdListEntriesGETWithHttpInfo(param: PersonsApiV2PersonsPersonIdListEntriesGETRequest, options?: ConfigurationOptions): Promise> { + return this.api.v2PersonsPersonIdListEntriesGETWithHttpInfo(param.personId, param.cursor, param.limit, options).toPromise(); } /** @@ -1268,26 +2400,44 @@ export class ObjectPersonsApi { * Get a Person\'s List Entries * @param param the request object */ - public getV2PersonsIdListEntries(param: PersonsApiGetV2PersonsIdListEntriesRequest, options?: ConfigurationOptions): Promise { - return this.api.getV2PersonsIdListEntries(param.id, param.cursor, param.limit, options).toPromise(); + public v2PersonsPersonIdListEntriesGET(param: PersonsApiV2PersonsPersonIdListEntriesGETRequest, options?: ConfigurationOptions): Promise { + return this.api.v2PersonsPersonIdListEntriesGET(param.personId, param.cursor, param.limit, options).toPromise(); } /** - * Returns metadata for all the Lists on which the given Person appears. + * Paginate through all Lists where the given Person appears as an entry and that you have access to view. Returns basic List information for each List that contains this Person. * Get a Person\'s Lists * @param param the request object */ - public getV2PersonsIdListsWithHttpInfo(param: PersonsApiGetV2PersonsIdListsRequest, options?: ConfigurationOptions): Promise> { - return this.api.getV2PersonsIdListsWithHttpInfo(param.id, param.cursor, param.limit, options).toPromise(); + public v2PersonsPersonIdListsGETWithHttpInfo(param: PersonsApiV2PersonsPersonIdListsGETRequest, options?: ConfigurationOptions): Promise> { + return this.api.v2PersonsPersonIdListsGETWithHttpInfo(param.personId, param.cursor, param.limit, options).toPromise(); } /** - * Returns metadata for all the Lists on which the given Person appears. + * Paginate through all Lists where the given Person appears as an entry and that you have access to view. Returns basic List information for each List that contains this Person. * Get a Person\'s Lists * @param param the request object */ - public getV2PersonsIdLists(param: PersonsApiGetV2PersonsIdListsRequest, options?: ConfigurationOptions): Promise { - return this.api.getV2PersonsIdLists(param.id, param.cursor, param.limit, options).toPromise(); + public v2PersonsPersonIdListsGET(param: PersonsApiV2PersonsPersonIdListsGETRequest, options?: ConfigurationOptions): Promise { + return this.api.v2PersonsPersonIdListsGET(param.personId, param.cursor, param.limit, options).toPromise(); + } + + /** + * | ⚠️ This endpoint is currently in BETA | |--| Returns notes for a given person id which includes directly attached notes, notes on meetings this person attended, and notes where this person is mentioned. You can filter notes using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|---------------------------------| | `creator.id` | Filter notes by the creator of the note | `int32` | `=` | `creator.id=1` | | `createdAt` | Filter notes by when it was created | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-02-04T10:48:24Z` | | `updatedAt` | Filter notes by when it was updated | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-02-03T10:48:24Z`| + * Get Notes for a Person + * @param param the request object + */ + public v2PersonsPersonIdNotesGETWithHttpInfo(param: PersonsApiV2PersonsPersonIdNotesGETRequest, options?: ConfigurationOptions): Promise> { + return this.api.v2PersonsPersonIdNotesGETWithHttpInfo(param.personId, param.filter, param.cursor, param.limit, param.totalCount, options).toPromise(); + } + + /** + * | ⚠️ This endpoint is currently in BETA | |--| Returns notes for a given person id which includes directly attached notes, notes on meetings this person attended, and notes where this person is mentioned. You can filter notes using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|---------------------------------| | `creator.id` | Filter notes by the creator of the note | `int32` | `=` | `creator.id=1` | | `createdAt` | Filter notes by when it was created | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-02-04T10:48:24Z` | | `updatedAt` | Filter notes by when it was updated | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-02-03T10:48:24Z`| + * Get Notes for a Person + * @param param the request object + */ + public v2PersonsPersonIdNotesGET(param: PersonsApiV2PersonsPersonIdNotesGETRequest, options?: ConfigurationOptions): Promise { + return this.api.v2PersonsPersonIdNotesGET(param.personId, param.filter, param.cursor, param.limit, param.totalCount, options).toPromise(); } } diff --git a/src/v2/generated/types/ObservableAPI.ts b/src/v2/generated/types/ObservableAPI.ts index b812b6b..9ffa17d 100644 --- a/src/v2/generated/types/ObservableAPI.ts +++ b/src/v2/generated/types/ObservableAPI.ts @@ -1,9 +1,10 @@ import { ResponseContext, RequestContext, HttpFile, HttpInfo } from '../http/http.ts'; -import { Configuration, ConfigurationOptions } from '../configuration.ts' +import { Configuration, ConfigurationOptions, mergeConfiguration } from '../configuration.ts' import type { Middleware } from '../middleware.ts'; import { Observable, of, from } from '../rxjsStub.ts'; import {mergeMap, map} from '../rxjsStub.ts'; import { Attendee } from '../models/Attendee.ts'; +import { AttendeesPreview } from '../models/AttendeesPreview.ts'; import { AuthenticationError } from '../models/AuthenticationError.ts'; import { AuthorizationError } from '../models/AuthorizationError.ts'; import { AuthorizationErrors } from '../models/AuthorizationErrors.ts'; @@ -13,7 +14,15 @@ import { CompaniesValue } from '../models/CompaniesValue.ts'; import { CompaniesValueUpdate } from '../models/CompaniesValueUpdate.ts'; import { Company } from '../models/Company.ts'; import { CompanyData } from '../models/CompanyData.ts'; +import { CompanyDataPaged } from '../models/CompanyDataPaged.ts'; import { CompanyListEntry } from '../models/CompanyListEntry.ts'; +import { CompanyMergeRequest } from '../models/CompanyMergeRequest.ts'; +import { CompanyMergeResponse } from '../models/CompanyMergeResponse.ts'; +import { CompanyMergeState } from '../models/CompanyMergeState.ts'; +import { CompanyMergeStatePaged } from '../models/CompanyMergeStatePaged.ts'; +import { CompanyMergeTask } from '../models/CompanyMergeTask.ts'; +import { CompanyMergeTaskPaged } from '../models/CompanyMergeTaskPaged.ts'; +import { CompanyMergeTaskResultsSummary } from '../models/CompanyMergeTaskResultsSummary.ts'; import { CompanyPaged } from '../models/CompanyPaged.ts'; import { CompanyReference } from '../models/CompanyReference.ts'; import { CompanyValue } from '../models/CompanyValue.ts'; @@ -40,10 +49,16 @@ import { FloatsValue } from '../models/FloatsValue.ts'; import { FormulaNumber } from '../models/FormulaNumber.ts'; import { FormulaValue } from '../models/FormulaValue.ts'; import { Grant } from '../models/Grant.ts'; -import { InlineObject } from '../models/InlineObject.ts'; -import { InlineObjectErrorsInner } from '../models/InlineObjectErrorsInner.ts'; import { Interaction } from '../models/Interaction.ts'; import { InteractionValue } from '../models/InteractionValue.ts'; +import { InteractionsCall } from '../models/InteractionsCall.ts'; +import { InteractionsCallPaged } from '../models/InteractionsCallPaged.ts'; +import { InteractionsChatMessage } from '../models/InteractionsChatMessage.ts'; +import { InteractionsChatMessagePaged } from '../models/InteractionsChatMessagePaged.ts'; +import { InteractionsEmail } from '../models/InteractionsEmail.ts'; +import { InteractionsEmailPaged } from '../models/InteractionsEmailPaged.ts'; +import { InteractionsMeeting } from '../models/InteractionsMeeting.ts'; +import { InteractionsMeetingPaged } from '../models/InteractionsMeetingPaged.ts'; import { List } from '../models/List.ts'; import { ListEntry } from '../models/ListEntry.ts'; import { ListEntryBatchOperationResponse } from '../models/ListEntryBatchOperationResponse.ts'; @@ -66,14 +81,47 @@ import { NotAcceptableError } from '../models/NotAcceptableError.ts'; import { NotFoundError } from '../models/NotFoundError.ts'; import { NotFoundErrors } from '../models/NotFoundErrors.ts'; import { NotImplementedError } from '../models/NotImplementedError.ts'; +import { NotesAiNotetakerReplyNote } from '../models/NotesAiNotetakerReplyNote.ts'; +import { NotesAiNotetakerRootNote } from '../models/NotesAiNotetakerRootNote.ts'; +import { NotesBaseNote } from '../models/NotesBaseNote.ts'; +import { NotesBaseReply } from '../models/NotesBaseReply.ts'; +import { NotesBaseReplyParent } from '../models/NotesBaseReplyParent.ts'; +import { NotesBaseRootNote } from '../models/NotesBaseRootNote.ts'; +import { NotesCallInteraction } from '../models/NotesCallInteraction.ts'; +import { NotesChatMessageInteraction } from '../models/NotesChatMessageInteraction.ts'; +import { NotesCompaniesPreview } from '../models/NotesCompaniesPreview.ts'; +import { NotesContent } from '../models/NotesContent.ts'; +import { NotesEmailInteraction } from '../models/NotesEmailInteraction.ts'; +import { NotesEntitiesNote } from '../models/NotesEntitiesNote.ts'; +import { NotesInteraction } from '../models/NotesInteraction.ts'; +import { NotesInteractionNote } from '../models/NotesInteractionNote.ts'; +import { NotesMeetingInteraction } from '../models/NotesMeetingInteraction.ts'; +import { NotesNote } from '../models/NotesNote.ts'; +import { NotesNotesPaged } from '../models/NotesNotesPaged.ts'; +import { NotesOpportunitiesPreview } from '../models/NotesOpportunitiesPreview.ts'; +import { NotesPermissionSettings } from '../models/NotesPermissionSettings.ts'; +import { NotesPersonMention } from '../models/NotesPersonMention.ts'; +import { NotesPersonsPreview } from '../models/NotesPersonsPreview.ts'; +import { NotesRepliesPaged } from '../models/NotesRepliesPaged.ts'; +import { NotesReply } from '../models/NotesReply.ts'; +import { NotesUserReplyNote } from '../models/NotesUserReplyNote.ts'; import { Opportunity } from '../models/Opportunity.ts'; import { OpportunityListEntry } from '../models/OpportunityListEntry.ts'; import { OpportunityPaged } from '../models/OpportunityPaged.ts'; import { OpportunityWithFields } from '../models/OpportunityWithFields.ts'; import { Pagination } from '../models/Pagination.ts'; +import { PaginationWithTotalCount } from '../models/PaginationWithTotalCount.ts'; import { Person } from '../models/Person.ts'; import { PersonData } from '../models/PersonData.ts'; +import { PersonDataPaged } from '../models/PersonDataPaged.ts'; +import { PersonDataPreview } from '../models/PersonDataPreview.ts'; import { PersonListEntry } from '../models/PersonListEntry.ts'; +import { PersonMergeRequest } from '../models/PersonMergeRequest.ts'; +import { PersonMergeResponse } from '../models/PersonMergeResponse.ts'; +import { PersonMergeState } from '../models/PersonMergeState.ts'; +import { PersonMergeStatePaged } from '../models/PersonMergeStatePaged.ts'; +import { PersonMergeTask } from '../models/PersonMergeTask.ts'; +import { PersonMergeTaskPaged } from '../models/PersonMergeTaskPaged.ts'; import { PersonPaged } from '../models/PersonPaged.ts'; import { PersonReference } from '../models/PersonReference.ts'; import { PersonValue } from '../models/PersonValue.ts'; @@ -86,6 +134,8 @@ import { RankedDropdownReference } from '../models/RankedDropdownReference.ts'; import { RankedDropdownValue } from '../models/RankedDropdownValue.ts'; import { RankedDropdownValueUpdate } from '../models/RankedDropdownValueUpdate.ts'; import { RateLimitError } from '../models/RateLimitError.ts'; +import { Responses400 } from '../models/Responses400.ts'; +import { Responses400ErrorsInner } from '../models/Responses400ErrorsInner.ts'; import { SavedView } from '../models/SavedView.ts'; import { SavedViewPaged } from '../models/SavedViewPaged.ts'; import { ServerError } from '../models/ServerError.ts'; @@ -115,1377 +165,1775 @@ export class ObservableAuthApi { } /** - * Returns metadata about the current user. + * Returns information about the authenticated user, their current organization, and API key permissions. Use this endpoint to verify your authentication and understand your available API access levels. * Get current user */ - public getV2AuthWhoamiWithHttpInfo(_options?: ConfigurationOptions): Observable> { - let _config = this.configuration; - let allMiddleware: Middleware[] = []; - if (_options && _options.middleware){ - const middlewareMergeStrategy = _options.middlewareMergeStrategy || 'replace' // default to replace behavior - // call-time middleware provided - const calltimeMiddleware: Middleware[] = _options.middleware; - - switch(middlewareMergeStrategy){ - case 'append': - allMiddleware = this.configuration.middleware.concat(calltimeMiddleware); - break; - case 'prepend': - allMiddleware = calltimeMiddleware.concat(this.configuration.middleware) - break; - case 'replace': - allMiddleware = calltimeMiddleware - break; - default: - throw new Error(`unrecognized middleware merge strategy '${middlewareMergeStrategy}'`) - } - } - if (_options){ - _config = { - baseServer: _options.baseServer || this.configuration.baseServer, - httpApi: _options.httpApi || this.configuration.httpApi, - authMethods: _options.authMethods || this.configuration.authMethods, - middleware: allMiddleware || this.configuration.middleware - }; - } - - const requestContextPromise = this.requestFactory.getV2AuthWhoami(_config); + public v2AuthWhoamiGETWithHttpInfo(_options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); + + const requestContextPromise = this.requestFactory.v2AuthWhoamiGET(_config); // build promise chain let middlewarePreObservable = from(requestContextPromise); - for (const middleware of allMiddleware) { + for (const middleware of _config.middleware) { middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); } - return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => this.configuration.httpApi.send(ctx))). + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). pipe(mergeMap((response: ResponseContext) => { let middlewarePostObservable = of(response); - for (const middleware of allMiddleware.reverse()) { + for (const middleware of _config.middleware.reverse()) { middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); } - return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.getV2AuthWhoamiWithHttpInfo(rsp))); + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2AuthWhoamiGETWithHttpInfo(rsp))); })); } /** - * Returns metadata about the current user. + * Returns information about the authenticated user, their current organization, and API key permissions. Use this endpoint to verify your authentication and understand your available API access levels. * Get current user */ - public getV2AuthWhoami(_options?: ConfigurationOptions): Observable { - return this.getV2AuthWhoamiWithHttpInfo(_options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + public v2AuthWhoamiGET(_options?: ConfigurationOptions): Observable { + return this.v2AuthWhoamiGETWithHttpInfo(_options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); } } -import { CompaniesApiRequestFactory, CompaniesApiResponseProcessor} from "../apis/CompaniesApi.ts"; -export class ObservableCompaniesApi { - private requestFactory: CompaniesApiRequestFactory; - private responseProcessor: CompaniesApiResponseProcessor; +import { CallsApiRequestFactory, CallsApiResponseProcessor} from "../apis/CallsApi.ts"; +export class ObservableCallsApi { + private requestFactory: CallsApiRequestFactory; + private responseProcessor: CallsApiResponseProcessor; private configuration: Configuration; public constructor( configuration: Configuration, - requestFactory?: CompaniesApiRequestFactory, - responseProcessor?: CompaniesApiResponseProcessor + requestFactory?: CallsApiRequestFactory, + responseProcessor?: CallsApiResponseProcessor ) { this.configuration = configuration; - this.requestFactory = requestFactory || new CompaniesApiRequestFactory(configuration); - this.responseProcessor = responseProcessor || new CompaniesApiResponseProcessor(); + this.requestFactory = requestFactory || new CallsApiRequestFactory(configuration); + this.responseProcessor = responseProcessor || new CallsApiResponseProcessor(); } /** - * Paginate through Companies in Affinity. Returns basic information and non-list-specific field data on each Company. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/companies/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Companies will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All Organizations directory\" [permission](#section/Getting-Started/Permissions). - * Get all Companies + * Paginate through all calls in Affinity. Returns basic information about the call interaction and its participants. Will only return calls that the current authenticated user has permission to see. You can filter calls using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|----------------------------------| | `id` | Unique identifier for Calls | `int64` | `=` | `id=1` | | `startTime` | Start time of when the Call was held | `datetime` | `>`, `<`, `>=`, `<=` | `sentAt>2025-01-01T01:00:00Z` | | `createdAt` | When the Call was created in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-01-01T01:00:00Z` | | `updatedAt` | When the Call was updated in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-01-01T01:00:00Z`| + * Get metadata on all Calls * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page - * @param [ids] Company IDs - * @param [fieldIds] Field IDs for which to return field data - * @param [fieldTypes] Field Types for which to return field data + * @param [filter] Filter options */ - public getV2CompaniesWithHttpInfo(cursor?: string, limit?: number, ids?: Array, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: ConfigurationOptions): Observable> { - let _config = this.configuration; - let allMiddleware: Middleware[] = []; - if (_options && _options.middleware){ - const middlewareMergeStrategy = _options.middlewareMergeStrategy || 'replace' // default to replace behavior - // call-time middleware provided - const calltimeMiddleware: Middleware[] = _options.middleware; - - switch(middlewareMergeStrategy){ - case 'append': - allMiddleware = this.configuration.middleware.concat(calltimeMiddleware); - break; - case 'prepend': - allMiddleware = calltimeMiddleware.concat(this.configuration.middleware) - break; - case 'replace': - allMiddleware = calltimeMiddleware - break; - default: - throw new Error(`unrecognized middleware merge strategy '${middlewareMergeStrategy}'`) - } - } - if (_options){ - _config = { - baseServer: _options.baseServer || this.configuration.baseServer, - httpApi: _options.httpApi || this.configuration.httpApi, - authMethods: _options.authMethods || this.configuration.authMethods, - middleware: allMiddleware || this.configuration.middleware - }; - } - - const requestContextPromise = this.requestFactory.getV2Companies(cursor, limit, ids, fieldIds, fieldTypes, _config); + public v2CallsGETWithHttpInfo(cursor?: string, limit?: number, filter?: string, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); + + const requestContextPromise = this.requestFactory.v2CallsGET(cursor, limit, filter, _config); // build promise chain let middlewarePreObservable = from(requestContextPromise); - for (const middleware of allMiddleware) { + for (const middleware of _config.middleware) { middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); } - return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => this.configuration.httpApi.send(ctx))). + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). pipe(mergeMap((response: ResponseContext) => { let middlewarePostObservable = of(response); - for (const middleware of allMiddleware.reverse()) { + for (const middleware of _config.middleware.reverse()) { middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); } - return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.getV2CompaniesWithHttpInfo(rsp))); + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2CallsGETWithHttpInfo(rsp))); })); } /** - * Paginate through Companies in Affinity. Returns basic information and non-list-specific field data on each Company. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/companies/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Companies will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All Organizations directory\" [permission](#section/Getting-Started/Permissions). - * Get all Companies + * Paginate through all calls in Affinity. Returns basic information about the call interaction and its participants. Will only return calls that the current authenticated user has permission to see. You can filter calls using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|----------------------------------| | `id` | Unique identifier for Calls | `int64` | `=` | `id=1` | | `startTime` | Start time of when the Call was held | `datetime` | `>`, `<`, `>=`, `<=` | `sentAt>2025-01-01T01:00:00Z` | | `createdAt` | When the Call was created in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-01-01T01:00:00Z` | | `updatedAt` | When the Call was updated in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-01-01T01:00:00Z`| + * Get metadata on all Calls * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page - * @param [ids] Company IDs - * @param [fieldIds] Field IDs for which to return field data - * @param [fieldTypes] Field Types for which to return field data + * @param [filter] Filter options */ - public getV2Companies(cursor?: string, limit?: number, ids?: Array, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: ConfigurationOptions): Observable { - return this.getV2CompaniesWithHttpInfo(cursor, limit, ids, fieldIds, fieldTypes, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + public v2CallsGET(cursor?: string, limit?: number, filter?: string, _options?: ConfigurationOptions): Observable { + return this.v2CallsGETWithHttpInfo(cursor, limit, filter, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + } + +} + +import { ChatMessagesApiRequestFactory, ChatMessagesApiResponseProcessor} from "../apis/ChatMessagesApi.ts"; +export class ObservableChatMessagesApi { + private requestFactory: ChatMessagesApiRequestFactory; + private responseProcessor: ChatMessagesApiResponseProcessor; + private configuration: Configuration; + + public constructor( + configuration: Configuration, + requestFactory?: ChatMessagesApiRequestFactory, + responseProcessor?: ChatMessagesApiResponseProcessor + ) { + this.configuration = configuration; + this.requestFactory = requestFactory || new ChatMessagesApiRequestFactory(configuration); + this.responseProcessor = responseProcessor || new ChatMessagesApiResponseProcessor(); } /** - * Returns metadata on non-list-specific Company Fields. Use the returned Field IDs to request field data from the GET `/v2/companies` and GET `/v2/companies/{id}` endpoints. - * Get metadata on Company Fields + * Paginate through all chat messages in Affinity. Returns basic information about the chat message interaction and its participants. Will only return chat messages that the current authenticated user has permission to see. You can filter chat messages using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|----------------------------------| | `id` | Unique identifier for Chat Messages | `int64` | `=` | `id=1` | | `sentAt` | When the Chat Message was sent at | `datetime` | `>`, `<`, `>=`, `<=` | `sentAt>2025-01-01T01:00:00Z` | | `createdAt` | When the Chat Message was created in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-01-01T01:00:00Z` | | `updatedAt` | When the Chat Message was updated in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-01-01T01:00:00Z`| + * Get metadata on all Chat Messages * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page + * @param [filter] Filter options */ - public getV2CompaniesFieldsWithHttpInfo(cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable> { - let _config = this.configuration; - let allMiddleware: Middleware[] = []; - if (_options && _options.middleware){ - const middlewareMergeStrategy = _options.middlewareMergeStrategy || 'replace' // default to replace behavior - // call-time middleware provided - const calltimeMiddleware: Middleware[] = _options.middleware; - - switch(middlewareMergeStrategy){ - case 'append': - allMiddleware = this.configuration.middleware.concat(calltimeMiddleware); - break; - case 'prepend': - allMiddleware = calltimeMiddleware.concat(this.configuration.middleware) - break; - case 'replace': - allMiddleware = calltimeMiddleware - break; - default: - throw new Error(`unrecognized middleware merge strategy '${middlewareMergeStrategy}'`) - } - } - if (_options){ - _config = { - baseServer: _options.baseServer || this.configuration.baseServer, - httpApi: _options.httpApi || this.configuration.httpApi, - authMethods: _options.authMethods || this.configuration.authMethods, - middleware: allMiddleware || this.configuration.middleware - }; - } - - const requestContextPromise = this.requestFactory.getV2CompaniesFields(cursor, limit, _config); + public v2ChatMessagesGETWithHttpInfo(cursor?: string, limit?: number, filter?: string, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); + + const requestContextPromise = this.requestFactory.v2ChatMessagesGET(cursor, limit, filter, _config); // build promise chain let middlewarePreObservable = from(requestContextPromise); - for (const middleware of allMiddleware) { + for (const middleware of _config.middleware) { middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); } - return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => this.configuration.httpApi.send(ctx))). + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). pipe(mergeMap((response: ResponseContext) => { let middlewarePostObservable = of(response); - for (const middleware of allMiddleware.reverse()) { + for (const middleware of _config.middleware.reverse()) { middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); } - return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.getV2CompaniesFieldsWithHttpInfo(rsp))); + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2ChatMessagesGETWithHttpInfo(rsp))); })); } /** - * Returns metadata on non-list-specific Company Fields. Use the returned Field IDs to request field data from the GET `/v2/companies` and GET `/v2/companies/{id}` endpoints. - * Get metadata on Company Fields + * Paginate through all chat messages in Affinity. Returns basic information about the chat message interaction and its participants. Will only return chat messages that the current authenticated user has permission to see. You can filter chat messages using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|----------------------------------| | `id` | Unique identifier for Chat Messages | `int64` | `=` | `id=1` | | `sentAt` | When the Chat Message was sent at | `datetime` | `>`, `<`, `>=`, `<=` | `sentAt>2025-01-01T01:00:00Z` | | `createdAt` | When the Chat Message was created in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-01-01T01:00:00Z` | | `updatedAt` | When the Chat Message was updated in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-01-01T01:00:00Z`| + * Get metadata on all Chat Messages * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page + * @param [filter] Filter options */ - public getV2CompaniesFields(cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable { - return this.getV2CompaniesFieldsWithHttpInfo(cursor, limit, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + public v2ChatMessagesGET(cursor?: string, limit?: number, filter?: string, _options?: ConfigurationOptions): Observable { + return this.v2ChatMessagesGETWithHttpInfo(cursor, limit, filter, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + } + +} + +import { CompaniesApiRequestFactory, CompaniesApiResponseProcessor} from "../apis/CompaniesApi.ts"; +export class ObservableCompaniesApi { + private requestFactory: CompaniesApiRequestFactory; + private responseProcessor: CompaniesApiResponseProcessor; + private configuration: Configuration; + + public constructor( + configuration: Configuration, + requestFactory?: CompaniesApiRequestFactory, + responseProcessor?: CompaniesApiResponseProcessor + ) { + this.configuration = configuration; + this.requestFactory = requestFactory || new CompaniesApiRequestFactory(configuration); + this.responseProcessor = responseProcessor || new CompaniesApiResponseProcessor(); } /** * Returns basic information and non-list-specific field data on the requested Company. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/companies/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Companies will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All Organizations directory\" [permission](#section/Getting-Started/Permissions). * Get a single Company - * @param id Company ID + * @param companyId Company ID * @param [fieldIds] Field IDs for which to return field data * @param [fieldTypes] Field Types for which to return field data */ - public getV2CompaniesIdWithHttpInfo(id: number, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: ConfigurationOptions): Observable> { - let _config = this.configuration; - let allMiddleware: Middleware[] = []; - if (_options && _options.middleware){ - const middlewareMergeStrategy = _options.middlewareMergeStrategy || 'replace' // default to replace behavior - // call-time middleware provided - const calltimeMiddleware: Middleware[] = _options.middleware; - - switch(middlewareMergeStrategy){ - case 'append': - allMiddleware = this.configuration.middleware.concat(calltimeMiddleware); - break; - case 'prepend': - allMiddleware = calltimeMiddleware.concat(this.configuration.middleware) - break; - case 'replace': - allMiddleware = calltimeMiddleware - break; - default: - throw new Error(`unrecognized middleware merge strategy '${middlewareMergeStrategy}'`) - } - } - if (_options){ - _config = { - baseServer: _options.baseServer || this.configuration.baseServer, - httpApi: _options.httpApi || this.configuration.httpApi, - authMethods: _options.authMethods || this.configuration.authMethods, - middleware: allMiddleware || this.configuration.middleware - }; - } - - const requestContextPromise = this.requestFactory.getV2CompaniesId(id, fieldIds, fieldTypes, _config); + public v2CompaniesCompanyIdGETWithHttpInfo(companyId: number, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); + + const requestContextPromise = this.requestFactory.v2CompaniesCompanyIdGET(companyId, fieldIds, fieldTypes, _config); // build promise chain let middlewarePreObservable = from(requestContextPromise); - for (const middleware of allMiddleware) { + for (const middleware of _config.middleware) { middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); } - return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => this.configuration.httpApi.send(ctx))). + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). pipe(mergeMap((response: ResponseContext) => { let middlewarePostObservable = of(response); - for (const middleware of allMiddleware.reverse()) { + for (const middleware of _config.middleware.reverse()) { middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); } - return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.getV2CompaniesIdWithHttpInfo(rsp))); + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2CompaniesCompanyIdGETWithHttpInfo(rsp))); })); } /** * Returns basic information and non-list-specific field data on the requested Company. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/companies/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Companies will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All Organizations directory\" [permission](#section/Getting-Started/Permissions). * Get a single Company - * @param id Company ID + * @param companyId Company ID * @param [fieldIds] Field IDs for which to return field data * @param [fieldTypes] Field Types for which to return field data */ - public getV2CompaniesId(id: number, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: ConfigurationOptions): Observable { - return this.getV2CompaniesIdWithHttpInfo(id, fieldIds, fieldTypes, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + public v2CompaniesCompanyIdGET(companyId: number, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: ConfigurationOptions): Observable { + return this.v2CompaniesCompanyIdGETWithHttpInfo(companyId, fieldIds, fieldTypes, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); } /** * Paginate through the List Entries (AKA rows) for the given Company across all Lists. Each List Entry includes field data for the Company, including list-specific field data. Each List Entry also includes metadata about its creation, i.e., when it was added to the List and by whom. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). * Get a Company\'s List Entries - * @param id Company ID + * @param companyId Company ID * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page */ - public getV2CompaniesIdListEntriesWithHttpInfo(id: number, cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable> { - let _config = this.configuration; - let allMiddleware: Middleware[] = []; - if (_options && _options.middleware){ - const middlewareMergeStrategy = _options.middlewareMergeStrategy || 'replace' // default to replace behavior - // call-time middleware provided - const calltimeMiddleware: Middleware[] = _options.middleware; - - switch(middlewareMergeStrategy){ - case 'append': - allMiddleware = this.configuration.middleware.concat(calltimeMiddleware); - break; - case 'prepend': - allMiddleware = calltimeMiddleware.concat(this.configuration.middleware) - break; - case 'replace': - allMiddleware = calltimeMiddleware - break; - default: - throw new Error(`unrecognized middleware merge strategy '${middlewareMergeStrategy}'`) - } - } - if (_options){ - _config = { - baseServer: _options.baseServer || this.configuration.baseServer, - httpApi: _options.httpApi || this.configuration.httpApi, - authMethods: _options.authMethods || this.configuration.authMethods, - middleware: allMiddleware || this.configuration.middleware - }; - } - - const requestContextPromise = this.requestFactory.getV2CompaniesIdListEntries(id, cursor, limit, _config); + public v2CompaniesCompanyIdListEntriesGETWithHttpInfo(companyId: number, cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); + + const requestContextPromise = this.requestFactory.v2CompaniesCompanyIdListEntriesGET(companyId, cursor, limit, _config); // build promise chain let middlewarePreObservable = from(requestContextPromise); - for (const middleware of allMiddleware) { + for (const middleware of _config.middleware) { middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); } - return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => this.configuration.httpApi.send(ctx))). + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). pipe(mergeMap((response: ResponseContext) => { let middlewarePostObservable = of(response); - for (const middleware of allMiddleware.reverse()) { + for (const middleware of _config.middleware.reverse()) { middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); } - return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.getV2CompaniesIdListEntriesWithHttpInfo(rsp))); + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2CompaniesCompanyIdListEntriesGETWithHttpInfo(rsp))); })); } /** * Paginate through the List Entries (AKA rows) for the given Company across all Lists. Each List Entry includes field data for the Company, including list-specific field data. Each List Entry also includes metadata about its creation, i.e., when it was added to the List and by whom. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). * Get a Company\'s List Entries - * @param id Company ID + * @param companyId Company ID * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page */ - public getV2CompaniesIdListEntries(id: number, cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable { - return this.getV2CompaniesIdListEntriesWithHttpInfo(id, cursor, limit, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + public v2CompaniesCompanyIdListEntriesGET(companyId: number, cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable { + return this.v2CompaniesCompanyIdListEntriesGETWithHttpInfo(companyId, cursor, limit, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); } /** - * Returns metadata for all the Lists on which the given Company appears. + * Paginate through all Lists where the given Company appears as an entry and that you have access to view. Returns basic List information for each List that contains this Company. * Get a Company\'s Lists - * @param id Company ID + * @param companyId Company ID * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page */ - public getV2CompaniesIdListsWithHttpInfo(id: number, cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable> { - let _config = this.configuration; - let allMiddleware: Middleware[] = []; - if (_options && _options.middleware){ - const middlewareMergeStrategy = _options.middlewareMergeStrategy || 'replace' // default to replace behavior - // call-time middleware provided - const calltimeMiddleware: Middleware[] = _options.middleware; - - switch(middlewareMergeStrategy){ - case 'append': - allMiddleware = this.configuration.middleware.concat(calltimeMiddleware); - break; - case 'prepend': - allMiddleware = calltimeMiddleware.concat(this.configuration.middleware) - break; - case 'replace': - allMiddleware = calltimeMiddleware - break; - default: - throw new Error(`unrecognized middleware merge strategy '${middlewareMergeStrategy}'`) - } - } - if (_options){ - _config = { - baseServer: _options.baseServer || this.configuration.baseServer, - httpApi: _options.httpApi || this.configuration.httpApi, - authMethods: _options.authMethods || this.configuration.authMethods, - middleware: allMiddleware || this.configuration.middleware - }; - } - - const requestContextPromise = this.requestFactory.getV2CompaniesIdLists(id, cursor, limit, _config); + public v2CompaniesCompanyIdListsGETWithHttpInfo(companyId: number, cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); + + const requestContextPromise = this.requestFactory.v2CompaniesCompanyIdListsGET(companyId, cursor, limit, _config); // build promise chain let middlewarePreObservable = from(requestContextPromise); - for (const middleware of allMiddleware) { + for (const middleware of _config.middleware) { middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); } - return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => this.configuration.httpApi.send(ctx))). + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). pipe(mergeMap((response: ResponseContext) => { let middlewarePostObservable = of(response); - for (const middleware of allMiddleware.reverse()) { + for (const middleware of _config.middleware.reverse()) { middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); } - return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.getV2CompaniesIdListsWithHttpInfo(rsp))); + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2CompaniesCompanyIdListsGETWithHttpInfo(rsp))); })); } /** - * Returns metadata for all the Lists on which the given Company appears. + * Paginate through all Lists where the given Company appears as an entry and that you have access to view. Returns basic List information for each List that contains this Company. * Get a Company\'s Lists - * @param id Company ID + * @param companyId Company ID + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + */ + public v2CompaniesCompanyIdListsGET(companyId: number, cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable { + return this.v2CompaniesCompanyIdListsGETWithHttpInfo(companyId, cursor, limit, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + } + + /** + * | ⚠️ This endpoint is currently in BETA | |--| Returns relevant notes for a given company which includes directly attached notes and notes attached to persons on this company. You can filter notes using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|---------------------------------| | `creator.id` | Filter notes by the creator of the note | `int32` | `=` | `creator.id=1` | | `createdAt` | Filter notes by when it was created | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-02-04T10:48:24Z` | | `updatedAt` | Filter notes by when it was updated | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-02-03T10:48:24Z`| + * Get Notes for a Company + * @param companyId Company\'s ID + * @param [filter] Filter options + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + * @param [totalCount] Include total count of the collection in the pagination response + */ + public v2CompaniesCompanyIdNotesGETWithHttpInfo(companyId: number, filter?: string, cursor?: string, limit?: number, totalCount?: boolean, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); + + const requestContextPromise = this.requestFactory.v2CompaniesCompanyIdNotesGET(companyId, filter, cursor, limit, totalCount, _config); + // build promise chain + let middlewarePreObservable = from(requestContextPromise); + for (const middleware of _config.middleware) { + middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); + } + + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). + pipe(mergeMap((response: ResponseContext) => { + let middlewarePostObservable = of(response); + for (const middleware of _config.middleware.reverse()) { + middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); + } + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2CompaniesCompanyIdNotesGETWithHttpInfo(rsp))); + })); + } + + /** + * | ⚠️ This endpoint is currently in BETA | |--| Returns relevant notes for a given company which includes directly attached notes and notes attached to persons on this company. You can filter notes using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|---------------------------------| | `creator.id` | Filter notes by the creator of the note | `int32` | `=` | `creator.id=1` | | `createdAt` | Filter notes by when it was created | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-02-04T10:48:24Z` | | `updatedAt` | Filter notes by when it was updated | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-02-03T10:48:24Z`| + * Get Notes for a Company + * @param companyId Company\'s ID + * @param [filter] Filter options + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + * @param [totalCount] Include total count of the collection in the pagination response + */ + public v2CompaniesCompanyIdNotesGET(companyId: number, filter?: string, cursor?: string, limit?: number, totalCount?: boolean, _options?: ConfigurationOptions): Observable { + return this.v2CompaniesCompanyIdNotesGETWithHttpInfo(companyId, filter, cursor, limit, totalCount, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + } + + /** + * Returns metadata on non-list-specific Company Fields. Use the returned Field IDs to request field data from the GET `/v2/companies` and GET `/v2/companies/{id}` endpoints. + * Get metadata on Company Fields + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + */ + public v2CompaniesFieldsGETWithHttpInfo(cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); + + const requestContextPromise = this.requestFactory.v2CompaniesFieldsGET(cursor, limit, _config); + // build promise chain + let middlewarePreObservable = from(requestContextPromise); + for (const middleware of _config.middleware) { + middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); + } + + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). + pipe(mergeMap((response: ResponseContext) => { + let middlewarePostObservable = of(response); + for (const middleware of _config.middleware.reverse()) { + middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); + } + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2CompaniesFieldsGETWithHttpInfo(rsp))); + })); + } + + /** + * Returns metadata on non-list-specific Company Fields. Use the returned Field IDs to request field data from the GET `/v2/companies` and GET `/v2/companies/{id}` endpoints. + * Get metadata on Company Fields + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + */ + public v2CompaniesFieldsGET(cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable { + return this.v2CompaniesFieldsGETWithHttpInfo(cursor, limit, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + } + + /** + * Paginate through Companies in Affinity. Returns basic information and non-list-specific field data on each Company. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/companies/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Companies will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All Organizations directory\" [permission](#section/Getting-Started/Permissions). + * Get all Companies + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + * @param [ids] Company IDs + * @param [fieldIds] Field IDs for which to return field data + * @param [fieldTypes] Field Types for which to return field data + */ + public v2CompaniesGETWithHttpInfo(cursor?: string, limit?: number, ids?: Array, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); + + const requestContextPromise = this.requestFactory.v2CompaniesGET(cursor, limit, ids, fieldIds, fieldTypes, _config); + // build promise chain + let middlewarePreObservable = from(requestContextPromise); + for (const middleware of _config.middleware) { + middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); + } + + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). + pipe(mergeMap((response: ResponseContext) => { + let middlewarePostObservable = of(response); + for (const middleware of _config.middleware.reverse()) { + middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); + } + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2CompaniesGETWithHttpInfo(rsp))); + })); + } + + /** + * Paginate through Companies in Affinity. Returns basic information and non-list-specific field data on each Company. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/companies/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Companies will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All Organizations directory\" [permission](#section/Getting-Started/Permissions). + * Get all Companies * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page + * @param [ids] Company IDs + * @param [fieldIds] Field IDs for which to return field data + * @param [fieldTypes] Field Types for which to return field data */ - public getV2CompaniesIdLists(id: number, cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable { - return this.getV2CompaniesIdListsWithHttpInfo(id, cursor, limit, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + public v2CompaniesGET(cursor?: string, limit?: number, ids?: Array, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: ConfigurationOptions): Observable { + return this.v2CompaniesGETWithHttpInfo(cursor, limit, ids, fieldIds, fieldTypes, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); } } -import { ListsApiRequestFactory, ListsApiResponseProcessor} from "../apis/ListsApi.ts"; -export class ObservableListsApi { - private requestFactory: ListsApiRequestFactory; - private responseProcessor: ListsApiResponseProcessor; +import { CompanyMergesApiRequestFactory, CompanyMergesApiResponseProcessor} from "../apis/CompanyMergesApi.ts"; +export class ObservableCompanyMergesApi { + private requestFactory: CompanyMergesApiRequestFactory; + private responseProcessor: CompanyMergesApiResponseProcessor; private configuration: Configuration; public constructor( configuration: Configuration, - requestFactory?: ListsApiRequestFactory, - responseProcessor?: ListsApiResponseProcessor + requestFactory?: CompanyMergesApiRequestFactory, + responseProcessor?: CompanyMergesApiResponseProcessor ) { this.configuration = configuration; - this.requestFactory = requestFactory || new ListsApiRequestFactory(configuration); - this.responseProcessor = responseProcessor || new ListsApiResponseProcessor(); + this.requestFactory = requestFactory || new CompanyMergesApiRequestFactory(configuration); + this.responseProcessor = responseProcessor || new CompanyMergesApiResponseProcessor(); } /** - * Returns metadata on the Saved Views on a List. - * Get metadata on Saved Views - * @param listId List ID + * Retrieve paginated company merges for the organization. Returns all company merges initiated by users in your organization, including their current status, the companies involved, and merge details. You can filter company merges using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties: | Property | Type | Operators | Values | Examples | |----------|------|-----------|--------|----------| | `status` | `enum` | `=` | `in-progress`, `success`, `failed` | `status=failed` | | `taskId` | `string` | `=` | | `taskId=789e0123-e45b-67c8-d901-234567890123` | Company merges are returned in reverse chronological order (most recent first). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get All Company Merges * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page + * @param [filter] Filter company merges using Affinity Filtering Language */ - public getV2ListsListidSavedViewsWithHttpInfo(listId: number, cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable> { - let _config = this.configuration; - let allMiddleware: Middleware[] = []; - if (_options && _options.middleware){ - const middlewareMergeStrategy = _options.middlewareMergeStrategy || 'replace' // default to replace behavior - // call-time middleware provided - const calltimeMiddleware: Middleware[] = _options.middleware; - - switch(middlewareMergeStrategy){ - case 'append': - allMiddleware = this.configuration.middleware.concat(calltimeMiddleware); - break; - case 'prepend': - allMiddleware = calltimeMiddleware.concat(this.configuration.middleware) - break; - case 'replace': - allMiddleware = calltimeMiddleware - break; - default: - throw new Error(`unrecognized middleware merge strategy '${middlewareMergeStrategy}'`) - } - } - if (_options){ - _config = { - baseServer: _options.baseServer || this.configuration.baseServer, - httpApi: _options.httpApi || this.configuration.httpApi, - authMethods: _options.authMethods || this.configuration.authMethods, - middleware: allMiddleware || this.configuration.middleware - }; - } - - const requestContextPromise = this.requestFactory.getV2ListsListidSavedViews(listId, cursor, limit, _config); + public v2CompanyMergesGETWithHttpInfo(cursor?: string, limit?: number, filter?: string, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); + + const requestContextPromise = this.requestFactory.v2CompanyMergesGET(cursor, limit, filter, _config); // build promise chain let middlewarePreObservable = from(requestContextPromise); - for (const middleware of allMiddleware) { + for (const middleware of _config.middleware) { middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); } - return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => this.configuration.httpApi.send(ctx))). + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). pipe(mergeMap((response: ResponseContext) => { let middlewarePostObservable = of(response); - for (const middleware of allMiddleware.reverse()) { + for (const middleware of _config.middleware.reverse()) { middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); } - return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.getV2ListsListidSavedViewsWithHttpInfo(rsp))); + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2CompanyMergesGETWithHttpInfo(rsp))); })); } /** - * Returns metadata on the Saved Views on a List. - * Get metadata on Saved Views - * @param listId List ID + * Retrieve paginated company merges for the organization. Returns all company merges initiated by users in your organization, including their current status, the companies involved, and merge details. You can filter company merges using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties: | Property | Type | Operators | Values | Examples | |----------|------|-----------|--------|----------| | `status` | `enum` | `=` | `in-progress`, `success`, `failed` | `status=failed` | | `taskId` | `string` | `=` | | `taskId=789e0123-e45b-67c8-d901-234567890123` | Company merges are returned in reverse chronological order (most recent first). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get All Company Merges * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page + * @param [filter] Filter company merges using Affinity Filtering Language */ - public getV2ListsListidSavedViews(listId: number, cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable { - return this.getV2ListsListidSavedViewsWithHttpInfo(listId, cursor, limit, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + public v2CompanyMergesGET(cursor?: string, limit?: number, filter?: string, _options?: ConfigurationOptions): Observable { + return this.v2CompanyMergesGETWithHttpInfo(cursor, limit, filter, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); } /** - * Returns metadata on a single Saved View. - * Get metadata on a single Saved View - * @param listId List ID - * @param viewId Saved view ID + * Retrieve the status and details of a specific company merge. Returns information about the company merge including its current status, the companies involved, timestamps, and any error information if the merge failed. The `mergeId` can be obtained from the response of the [Get All Company Merges](#tag/companyMerges/operation/v2_company-merges__GET) endpoint, or by filtering company merges by task ID using `/v2/company-merges?filter=taskId={taskId}` after initiating a merge. Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get Company Merge + * @param mergeId Company merge ID + */ + public v2CompanyMergesMergeIdGETWithHttpInfo(mergeId: number, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); + + const requestContextPromise = this.requestFactory.v2CompanyMergesMergeIdGET(mergeId, _config); + // build promise chain + let middlewarePreObservable = from(requestContextPromise); + for (const middleware of _config.middleware) { + middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); + } + + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). + pipe(mergeMap((response: ResponseContext) => { + let middlewarePostObservable = of(response); + for (const middleware of _config.middleware.reverse()) { + middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); + } + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2CompanyMergesMergeIdGETWithHttpInfo(rsp))); + })); + } + + /** + * Retrieve the status and details of a specific company merge. Returns information about the company merge including its current status, the companies involved, timestamps, and any error information if the merge failed. The `mergeId` can be obtained from the response of the [Get All Company Merges](#tag/companyMerges/operation/v2_company-merges__GET) endpoint, or by filtering company merges by task ID using `/v2/company-merges?filter=taskId={taskId}` after initiating a merge. Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get Company Merge + * @param mergeId Company merge ID + */ + public v2CompanyMergesMergeIdGET(mergeId: number, _options?: ConfigurationOptions): Observable { + return this.v2CompanyMergesMergeIdGETWithHttpInfo(mergeId, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + } + + /** + * Initiate a company merge to combine a duplicate company profile into a primary company profile. This is an asynchronous process that will merge all data from the duplicate company into the primary company. Once the merge is initiated, you can track its progress using the returned [task URL](#tag/companyMerges/operation/v2_tasks_company-merges_taskId__GET). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Initiate Company Merge + * @param companyMergeRequest + */ + public v2CompanyMergesPOSTWithHttpInfo(companyMergeRequest: CompanyMergeRequest, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); + + const requestContextPromise = this.requestFactory.v2CompanyMergesPOST(companyMergeRequest, _config); + // build promise chain + let middlewarePreObservable = from(requestContextPromise); + for (const middleware of _config.middleware) { + middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); + } + + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). + pipe(mergeMap((response: ResponseContext) => { + let middlewarePostObservable = of(response); + for (const middleware of _config.middleware.reverse()) { + middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); + } + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2CompanyMergesPOSTWithHttpInfo(rsp))); + })); + } + + /** + * Initiate a company merge to combine a duplicate company profile into a primary company profile. This is an asynchronous process that will merge all data from the duplicate company into the primary company. Once the merge is initiated, you can track its progress using the returned [task URL](#tag/companyMerges/operation/v2_tasks_company-merges_taskId__GET). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Initiate Company Merge + * @param companyMergeRequest + */ + public v2CompanyMergesPOST(companyMergeRequest: CompanyMergeRequest, _options?: ConfigurationOptions): Observable { + return this.v2CompanyMergesPOSTWithHttpInfo(companyMergeRequest, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + } + + /** + * Retrieve paginated company merge tasks for the organization. Returns all merge tasks initiated by users in your organization, including their current status, the companies involved, and task details. You can filter tasks using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties: | Property | Type | Operators | Values | Examples | |----------|------|-----------|--------|----------| | `status` | `enum` | `=` | `in-progress`, `success`, `failed` | `status=failed` | Tasks are returned in reverse chronological order (most recent first). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get All Company Merge Tasks + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + * @param [filter] Filter tasks using Affinity Filtering Language + */ + public v2TasksCompanyMergesGETWithHttpInfo(cursor?: string, limit?: number, filter?: string, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); + + const requestContextPromise = this.requestFactory.v2TasksCompanyMergesGET(cursor, limit, filter, _config); + // build promise chain + let middlewarePreObservable = from(requestContextPromise); + for (const middleware of _config.middleware) { + middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); + } + + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). + pipe(mergeMap((response: ResponseContext) => { + let middlewarePostObservable = of(response); + for (const middleware of _config.middleware.reverse()) { + middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); + } + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2TasksCompanyMergesGETWithHttpInfo(rsp))); + })); + } + + /** + * Retrieve paginated company merge tasks for the organization. Returns all merge tasks initiated by users in your organization, including their current status, the companies involved, and task details. You can filter tasks using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties: | Property | Type | Operators | Values | Examples | |----------|------|-----------|--------|----------| | `status` | `enum` | `=` | `in-progress`, `success`, `failed` | `status=failed` | Tasks are returned in reverse chronological order (most recent first). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get All Company Merge Tasks + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + * @param [filter] Filter tasks using Affinity Filtering Language + */ + public v2TasksCompanyMergesGET(cursor?: string, limit?: number, filter?: string, _options?: ConfigurationOptions): Observable { + return this.v2TasksCompanyMergesGETWithHttpInfo(cursor, limit, filter, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + } + + /** + * Retrieve the status and details of a specific task for company merges. Returns information about the company merges for a specific task including its overall status, number of merges in-progress, completed, and failed. Detailed information about individual merges for this task can be found by querying: `/v2/company-merges?filter=taskId={taskId}` See [Company Merges](#tag/companyMerges/operation/v2_company-merges__GET) for more details. Task statuses: - `in-progress`: The merge task is currently being processed. - `success`: The merge task completed successfully. - `failed`: The merge task failed. Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get Company Merge Task + * @param taskId Company merge task ID + */ + public v2TasksCompanyMergesTaskIdGETWithHttpInfo(taskId: string, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); + + const requestContextPromise = this.requestFactory.v2TasksCompanyMergesTaskIdGET(taskId, _config); + // build promise chain + let middlewarePreObservable = from(requestContextPromise); + for (const middleware of _config.middleware) { + middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); + } + + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). + pipe(mergeMap((response: ResponseContext) => { + let middlewarePostObservable = of(response); + for (const middleware of _config.middleware.reverse()) { + middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); + } + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2TasksCompanyMergesTaskIdGETWithHttpInfo(rsp))); + })); + } + + /** + * Retrieve the status and details of a specific task for company merges. Returns information about the company merges for a specific task including its overall status, number of merges in-progress, completed, and failed. Detailed information about individual merges for this task can be found by querying: `/v2/company-merges?filter=taskId={taskId}` See [Company Merges](#tag/companyMerges/operation/v2_company-merges__GET) for more details. Task statuses: - `in-progress`: The merge task is currently being processed. - `success`: The merge task completed successfully. - `failed`: The merge task failed. Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get Company Merge Task + * @param taskId Company merge task ID + */ + public v2TasksCompanyMergesTaskIdGET(taskId: string, _options?: ConfigurationOptions): Observable { + return this.v2TasksCompanyMergesTaskIdGETWithHttpInfo(taskId, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + } + +} + +import { EmailsApiRequestFactory, EmailsApiResponseProcessor} from "../apis/EmailsApi.ts"; +export class ObservableEmailsApi { + private requestFactory: EmailsApiRequestFactory; + private responseProcessor: EmailsApiResponseProcessor; + private configuration: Configuration; + + public constructor( + configuration: Configuration, + requestFactory?: EmailsApiRequestFactory, + responseProcessor?: EmailsApiResponseProcessor + ) { + this.configuration = configuration; + this.requestFactory = requestFactory || new EmailsApiRequestFactory(configuration); + this.responseProcessor = responseProcessor || new EmailsApiResponseProcessor(); + } + + /** + * Paginate through all emails in Affinity. Returns basic information about the email interaction and its participants. Will only return emails or subject lines that the current authenticated user has permission to see. You can filter emails using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|----------------------------------| | `id` | Unique identifier for Emails | `int64` | `=` | `id=1` | | `sentAt` | When the Email was sent at | `datetime` | `>`, `<`, `>=`, `<=` | `sentAt>2025-01-01T01:00:00Z` | | `createdAt` | When the Email was created in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-01-01T01:00:00Z` | | `updatedAt` | When the Email was updated in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-01-01T01:00:00Z`| + * Get metadata on all Emails + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + * @param [filter] Filter options + */ + public v2EmailsGETWithHttpInfo(cursor?: string, limit?: number, filter?: string, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); + + const requestContextPromise = this.requestFactory.v2EmailsGET(cursor, limit, filter, _config); + // build promise chain + let middlewarePreObservable = from(requestContextPromise); + for (const middleware of _config.middleware) { + middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); + } + + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). + pipe(mergeMap((response: ResponseContext) => { + let middlewarePostObservable = of(response); + for (const middleware of _config.middleware.reverse()) { + middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); + } + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2EmailsGETWithHttpInfo(rsp))); + })); + } + + /** + * Paginate through all emails in Affinity. Returns basic information about the email interaction and its participants. Will only return emails or subject lines that the current authenticated user has permission to see. You can filter emails using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|----------------------------------| | `id` | Unique identifier for Emails | `int64` | `=` | `id=1` | | `sentAt` | When the Email was sent at | `datetime` | `>`, `<`, `>=`, `<=` | `sentAt>2025-01-01T01:00:00Z` | | `createdAt` | When the Email was created in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-01-01T01:00:00Z` | | `updatedAt` | When the Email was updated in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-01-01T01:00:00Z`| + * Get metadata on all Emails + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + * @param [filter] Filter options + */ + public v2EmailsGET(cursor?: string, limit?: number, filter?: string, _options?: ConfigurationOptions): Observable { + return this.v2EmailsGETWithHttpInfo(cursor, limit, filter, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + } + +} + +import { ListsApiRequestFactory, ListsApiResponseProcessor} from "../apis/ListsApi.ts"; +export class ObservableListsApi { + private requestFactory: ListsApiRequestFactory; + private responseProcessor: ListsApiResponseProcessor; + private configuration: Configuration; + + public constructor( + configuration: Configuration, + requestFactory?: ListsApiRequestFactory, + responseProcessor?: ListsApiResponseProcessor + ) { + this.configuration = configuration; + this.requestFactory = requestFactory || new ListsApiRequestFactory(configuration); + this.responseProcessor = responseProcessor || new ListsApiResponseProcessor(); + } + + /** + * Paginate through all Lists in your organization that you have access to view. Returns basic information about each List, including name, owner, and privacy settings. + * Get metadata on all Lists + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + */ + public v2ListsGETWithHttpInfo(cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); + + const requestContextPromise = this.requestFactory.v2ListsGET(cursor, limit, _config); + // build promise chain + let middlewarePreObservable = from(requestContextPromise); + for (const middleware of _config.middleware) { + middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); + } + + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). + pipe(mergeMap((response: ResponseContext) => { + let middlewarePostObservable = of(response); + for (const middleware of _config.middleware.reverse()) { + middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); + } + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2ListsGETWithHttpInfo(rsp))); + })); + } + + /** + * Paginate through all Lists in your organization that you have access to view. Returns basic information about each List, including name, owner, and privacy settings. + * Get metadata on all Lists + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + */ + public v2ListsGET(cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable { + return this.v2ListsGETWithHttpInfo(cursor, limit, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + } + + /** + * Returns metadata on the Fields available on a single List. Use the returned Field IDs to request field data from the GET `/v2/lists/{listId}/list-entries` endpoint. + * Get metadata on a single List\'s Fields + * @param listId List ID + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + */ + public v2ListsListIdFieldsGETWithHttpInfo(listId: number, cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); + + const requestContextPromise = this.requestFactory.v2ListsListIdFieldsGET(listId, cursor, limit, _config); + // build promise chain + let middlewarePreObservable = from(requestContextPromise); + for (const middleware of _config.middleware) { + middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); + } + + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). + pipe(mergeMap((response: ResponseContext) => { + let middlewarePostObservable = of(response); + for (const middleware of _config.middleware.reverse()) { + middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); + } + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2ListsListIdFieldsGETWithHttpInfo(rsp))); + })); + } + + /** + * Returns metadata on the Fields available on a single List. Use the returned Field IDs to request field data from the GET `/v2/lists/{listId}/list-entries` endpoint. + * Get metadata on a single List\'s Fields + * @param listId List ID + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + */ + public v2ListsListIdFieldsGET(listId: number, cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable { + return this.v2ListsListIdFieldsGETWithHttpInfo(listId, cursor, limit, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + } + + /** + * Retrieve detailed information about a specific List you have access to view. Returns List configuration including name, owner, privacy settings, and creation details. + * Get metadata on a single List + * @param listId List ID + */ + public v2ListsListIdGETWithHttpInfo(listId: number, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); + + const requestContextPromise = this.requestFactory.v2ListsListIdGET(listId, _config); + // build promise chain + let middlewarePreObservable = from(requestContextPromise); + for (const middleware of _config.middleware) { + middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); + } + + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). + pipe(mergeMap((response: ResponseContext) => { + let middlewarePostObservable = of(response); + for (const middleware of _config.middleware.reverse()) { + middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); + } + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2ListsListIdGETWithHttpInfo(rsp))); + })); + } + + /** + * Retrieve detailed information about a specific List you have access to view. Returns List configuration including name, owner, privacy settings, and creation details. + * Get metadata on a single List + * @param listId List ID + */ + public v2ListsListIdGET(listId: number, _options?: ConfigurationOptions): Observable { + return this.v2ListsListIdGETWithHttpInfo(listId, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + } + + /** + * Paginate through the List Entries (AKA rows) on a given List. Returns basic information and field data, including list-specific field data, on each Company, Person, or Opportunity on the List. List Entries also include metadata about their creation, i.e., when they were added to the List and by whom. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/lists/{listId}/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, List Entries will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Get all List Entries on a List + * @param listId List ID + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + * @param [fieldIds] Field IDs for which to return field data + * @param [fieldTypes] Field Types for which to return field data + */ + public v2ListsListIdListEntriesGETWithHttpInfo(listId: number, cursor?: string, limit?: number, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'list' | 'relationship-intelligence'>, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); + + const requestContextPromise = this.requestFactory.v2ListsListIdListEntriesGET(listId, cursor, limit, fieldIds, fieldTypes, _config); + // build promise chain + let middlewarePreObservable = from(requestContextPromise); + for (const middleware of _config.middleware) { + middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); + } + + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). + pipe(mergeMap((response: ResponseContext) => { + let middlewarePostObservable = of(response); + for (const middleware of _config.middleware.reverse()) { + middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); + } + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2ListsListIdListEntriesGETWithHttpInfo(rsp))); + })); + } + + /** + * Paginate through the List Entries (AKA rows) on a given List. Returns basic information and field data, including list-specific field data, on each Company, Person, or Opportunity on the List. List Entries also include metadata about their creation, i.e., when they were added to the List and by whom. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/lists/{listId}/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, List Entries will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Get all List Entries on a List + * @param listId List ID + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + * @param [fieldIds] Field IDs for which to return field data + * @param [fieldTypes] Field Types for which to return field data + */ + public v2ListsListIdListEntriesGET(listId: number, cursor?: string, limit?: number, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'list' | 'relationship-intelligence'>, _options?: ConfigurationOptions): Observable { + return this.v2ListsListIdListEntriesGETWithHttpInfo(listId, cursor, limit, fieldIds, fieldTypes, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + } + + /** + * Returns a single field value on a list entry. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Get a single field value + * @param listId List ID + * @param listEntryId List Entry ID + * @param fieldId Field ID + */ + public v2ListsListIdListEntriesListEntryIdFieldsFieldIdGETWithHttpInfo(listId: number, listEntryId: number, fieldId: string, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); + + const requestContextPromise = this.requestFactory.v2ListsListIdListEntriesListEntryIdFieldsFieldIdGET(listId, listEntryId, fieldId, _config); + // build promise chain + let middlewarePreObservable = from(requestContextPromise); + for (const middleware of _config.middleware) { + middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); + } + + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). + pipe(mergeMap((response: ResponseContext) => { + let middlewarePostObservable = of(response); + for (const middleware of _config.middleware.reverse()) { + middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); + } + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2ListsListIdListEntriesListEntryIdFieldsFieldIdGETWithHttpInfo(rsp))); + })); + } + + /** + * Returns a single field value on a list entry. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Get a single field value + * @param listId List ID + * @param listEntryId List Entry ID + * @param fieldId Field ID + */ + public v2ListsListIdListEntriesListEntryIdFieldsFieldIdGET(listId: number, listEntryId: number, fieldId: string, _options?: ConfigurationOptions): Observable { + return this.v2ListsListIdListEntriesListEntryIdFieldsFieldIdGETWithHttpInfo(listId, listEntryId, fieldId, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + } + + /** + * Update a single field value. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Update a single field value on a List Entry + * @param listId List ID + * @param listEntryId List Entry ID + * @param fieldId Field ID + * @param fieldUpdate + */ + public v2ListsListIdListEntriesListEntryIdFieldsFieldIdPOSTWithHttpInfo(listId: number, listEntryId: number, fieldId: string, fieldUpdate: FieldUpdate, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); + + const requestContextPromise = this.requestFactory.v2ListsListIdListEntriesListEntryIdFieldsFieldIdPOST(listId, listEntryId, fieldId, fieldUpdate, _config); + // build promise chain + let middlewarePreObservable = from(requestContextPromise); + for (const middleware of _config.middleware) { + middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); + } + + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). + pipe(mergeMap((response: ResponseContext) => { + let middlewarePostObservable = of(response); + for (const middleware of _config.middleware.reverse()) { + middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); + } + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2ListsListIdListEntriesListEntryIdFieldsFieldIdPOSTWithHttpInfo(rsp))); + })); + } + + /** + * Update a single field value. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Update a single field value on a List Entry + * @param listId List ID + * @param listEntryId List Entry ID + * @param fieldId Field ID + * @param fieldUpdate + */ + public v2ListsListIdListEntriesListEntryIdFieldsFieldIdPOST(listId: number, listEntryId: number, fieldId: string, fieldUpdate: FieldUpdate, _options?: ConfigurationOptions): Observable { + return this.v2ListsListIdListEntriesListEntryIdFieldsFieldIdPOSTWithHttpInfo(listId, listEntryId, fieldId, fieldUpdate, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + } + + /** + * Paginate through all field values on a single list entry. All fields will be included by default. The `ids` and `types` parameters can be used to filter the collection. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Get field values on a single List Entry + * @param listId List ID + * @param listEntryId List Entry ID + * @param [ids] Field IDs for which to return field data + * @param [types] Field Types for which to return field data + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + */ + public v2ListsListIdListEntriesListEntryIdFieldsGETWithHttpInfo(listId: number, listEntryId: number, ids?: Array, types?: Array<'enriched' | 'global' | 'list' | 'relationship-intelligence'>, cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); + + const requestContextPromise = this.requestFactory.v2ListsListIdListEntriesListEntryIdFieldsGET(listId, listEntryId, ids, types, cursor, limit, _config); + // build promise chain + let middlewarePreObservable = from(requestContextPromise); + for (const middleware of _config.middleware) { + middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); + } + + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). + pipe(mergeMap((response: ResponseContext) => { + let middlewarePostObservable = of(response); + for (const middleware of _config.middleware.reverse()) { + middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); + } + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2ListsListIdListEntriesListEntryIdFieldsGETWithHttpInfo(rsp))); + })); + } + + /** + * Paginate through all field values on a single list entry. All fields will be included by default. The `ids` and `types` parameters can be used to filter the collection. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Get field values on a single List Entry + * @param listId List ID + * @param listEntryId List Entry ID + * @param [ids] Field IDs for which to return field data + * @param [types] Field Types for which to return field data + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + */ + public v2ListsListIdListEntriesListEntryIdFieldsGET(listId: number, listEntryId: number, ids?: Array, types?: Array<'enriched' | 'global' | 'list' | 'relationship-intelligence'>, cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable { + return this.v2ListsListIdListEntriesListEntryIdFieldsGETWithHttpInfo(listId, listEntryId, ids, types, cursor, limit, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + } + + /** + * Perform batch operations on a list entry\'s fields. Currently the only operation at the endpoint is `update-fields`, which allows you to update multiple field values with a single request. This is equivalent to calling [the single field update](#operation/v2_lists_listId_list-entries_listEntryId_fields_fieldId__POST) endpoint multiple times. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Perform batch operations on a list entry\'s fields + * @param listId List ID + * @param listEntryId List Entry ID + * @param body + */ + public v2ListsListIdListEntriesListEntryIdFieldsPATCHWithHttpInfo(listId: number, listEntryId: number, body: ListEntryBatchOperationUpdateFields, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); + + const requestContextPromise = this.requestFactory.v2ListsListIdListEntriesListEntryIdFieldsPATCH(listId, listEntryId, body, _config); + // build promise chain + let middlewarePreObservable = from(requestContextPromise); + for (const middleware of _config.middleware) { + middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); + } + + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). + pipe(mergeMap((response: ResponseContext) => { + let middlewarePostObservable = of(response); + for (const middleware of _config.middleware.reverse()) { + middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); + } + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2ListsListIdListEntriesListEntryIdFieldsPATCHWithHttpInfo(rsp))); + })); + } + + /** + * Perform batch operations on a list entry\'s fields. Currently the only operation at the endpoint is `update-fields`, which allows you to update multiple field values with a single request. This is equivalent to calling [the single field update](#operation/v2_lists_listId_list-entries_listEntryId_fields_fieldId__POST) endpoint multiple times. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Perform batch operations on a list entry\'s fields + * @param listId List ID + * @param listEntryId List Entry ID + * @param body + */ + public v2ListsListIdListEntriesListEntryIdFieldsPATCH(listId: number, listEntryId: number, body: ListEntryBatchOperationUpdateFields, _options?: ConfigurationOptions): Observable { + return this.v2ListsListIdListEntriesListEntryIdFieldsPATCHWithHttpInfo(listId, listEntryId, body, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + } + + /** + * Retrieve a single list entry. Returns basic information and field data, including list-specific field data. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/lists/{listId}/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, the List Entry will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Get a single List Entry on a List + * @param listId List ID + * @param listEntryId List Entry ID + * @param [fieldIds] Field IDs for which to return field data + * @param [fieldTypes] Field Types for which to return field data + */ + public v2ListsListIdListEntriesListEntryIdGETWithHttpInfo(listId: number, listEntryId: number, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'list' | 'relationship-intelligence'>, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); + + const requestContextPromise = this.requestFactory.v2ListsListIdListEntriesListEntryIdGET(listId, listEntryId, fieldIds, fieldTypes, _config); + // build promise chain + let middlewarePreObservable = from(requestContextPromise); + for (const middleware of _config.middleware) { + middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); + } + + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). + pipe(mergeMap((response: ResponseContext) => { + let middlewarePostObservable = of(response); + for (const middleware of _config.middleware.reverse()) { + middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); + } + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2ListsListIdListEntriesListEntryIdGETWithHttpInfo(rsp))); + })); + } + + /** + * Retrieve a single list entry. Returns basic information and field data, including list-specific field data. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/lists/{listId}/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, the List Entry will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Get a single List Entry on a List + * @param listId List ID + * @param listEntryId List Entry ID + * @param [fieldIds] Field IDs for which to return field data + * @param [fieldTypes] Field Types for which to return field data + */ + public v2ListsListIdListEntriesListEntryIdGET(listId: number, listEntryId: number, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'list' | 'relationship-intelligence'>, _options?: ConfigurationOptions): Observable { + return this.v2ListsListIdListEntriesListEntryIdGETWithHttpInfo(listId, listEntryId, fieldIds, fieldTypes, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + } + + /** + * Paginate through all Saved Views you have access to view for a specific List. Returns Saved View configurations including name, column settings, and owner information. + * Get metadata on Saved Views + * @param listId List ID + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + */ + public v2ListsListIdSavedViewsGETWithHttpInfo(listId: number, cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); + + const requestContextPromise = this.requestFactory.v2ListsListIdSavedViewsGET(listId, cursor, limit, _config); + // build promise chain + let middlewarePreObservable = from(requestContextPromise); + for (const middleware of _config.middleware) { + middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); + } + + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). + pipe(mergeMap((response: ResponseContext) => { + let middlewarePostObservable = of(response); + for (const middleware of _config.middleware.reverse()) { + middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); + } + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2ListsListIdSavedViewsGETWithHttpInfo(rsp))); + })); + } + + /** + * Paginate through all Saved Views you have access to view for a specific List. Returns Saved View configurations including name, column settings, and owner information. + * Get metadata on Saved Views + * @param listId List ID + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + */ + public v2ListsListIdSavedViewsGET(listId: number, cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable { + return this.v2ListsListIdSavedViewsGETWithHttpInfo(listId, cursor, limit, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + } + + /** + * Retrieve detailed information about a specific Saved View you have access to view. Returns complete Saved View configuration including name, sorting, and column visibility settings. + * Get metadata on a single Saved View + * @param listId List ID + * @param viewId Saved view ID + */ + public v2ListsListIdSavedViewsViewIdGETWithHttpInfo(listId: number, viewId: number, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); + + const requestContextPromise = this.requestFactory.v2ListsListIdSavedViewsViewIdGET(listId, viewId, _config); + // build promise chain + let middlewarePreObservable = from(requestContextPromise); + for (const middleware of _config.middleware) { + middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); + } + + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). + pipe(mergeMap((response: ResponseContext) => { + let middlewarePostObservable = of(response); + for (const middleware of _config.middleware.reverse()) { + middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); + } + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2ListsListIdSavedViewsViewIdGETWithHttpInfo(rsp))); + })); + } + + /** + * Retrieve detailed information about a specific Saved View you have access to view. Returns complete Saved View configuration including name, sorting, and column visibility settings. + * Get metadata on a single Saved View + * @param listId List ID + * @param viewId Saved view ID + */ + public v2ListsListIdSavedViewsViewIdGET(listId: number, viewId: number, _options?: ConfigurationOptions): Observable { + return this.v2ListsListIdSavedViewsViewIdGETWithHttpInfo(listId, viewId, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + } + + /** + * Paginate through the List Entries (AKA rows) on a given Saved View. Use this endpoint when you need to filter entities or only want **some** field data to be returned: This endpoint respects the filters set on a Saved View via web app, and only returns field data corresponding to the columns that have been pulled into the Saved View via web app. Though this endpoint respects the Saved View\'s filters and column/Field selection, it does not yet preserve sort order. This endpoint also only supports **sheet-type Saved Views**, and not board- or dashboard-type Saved Views. See the [Data Model](#section/Data-Model) section for more information about Saved Views. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Get all List Entries on a Saved View + * @param listId List ID + * @param viewId Saved view ID + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + */ + public v2ListsListIdSavedViewsViewIdListEntriesGETWithHttpInfo(listId: number, viewId: number, cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); + + const requestContextPromise = this.requestFactory.v2ListsListIdSavedViewsViewIdListEntriesGET(listId, viewId, cursor, limit, _config); + // build promise chain + let middlewarePreObservable = from(requestContextPromise); + for (const middleware of _config.middleware) { + middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); + } + + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). + pipe(mergeMap((response: ResponseContext) => { + let middlewarePostObservable = of(response); + for (const middleware of _config.middleware.reverse()) { + middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); + } + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2ListsListIdSavedViewsViewIdListEntriesGETWithHttpInfo(rsp))); + })); + } + + /** + * Paginate through the List Entries (AKA rows) on a given Saved View. Use this endpoint when you need to filter entities or only want **some** field data to be returned: This endpoint respects the filters set on a Saved View via web app, and only returns field data corresponding to the columns that have been pulled into the Saved View via web app. Though this endpoint respects the Saved View\'s filters and column/Field selection, it does not yet preserve sort order. This endpoint also only supports **sheet-type Saved Views**, and not board- or dashboard-type Saved Views. See the [Data Model](#section/Data-Model) section for more information about Saved Views. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Get all List Entries on a Saved View + * @param listId List ID + * @param viewId Saved view ID + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + */ + public v2ListsListIdSavedViewsViewIdListEntriesGET(listId: number, viewId: number, cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable { + return this.v2ListsListIdSavedViewsViewIdListEntriesGETWithHttpInfo(listId, viewId, cursor, limit, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + } + +} + +import { MeetingsApiRequestFactory, MeetingsApiResponseProcessor} from "../apis/MeetingsApi.ts"; +export class ObservableMeetingsApi { + private requestFactory: MeetingsApiRequestFactory; + private responseProcessor: MeetingsApiResponseProcessor; + private configuration: Configuration; + + public constructor( + configuration: Configuration, + requestFactory?: MeetingsApiRequestFactory, + responseProcessor?: MeetingsApiResponseProcessor + ) { + this.configuration = configuration; + this.requestFactory = requestFactory || new MeetingsApiRequestFactory(configuration); + this.responseProcessor = responseProcessor || new MeetingsApiResponseProcessor(); + } + + /** + * Paginate through all Meetings in Affinity. Returns basic information about past and future meeting interactions and its attendees. You can filter meetings using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|----------------------------------| | `id` | Unique identifier for Meetings | `int64` | `=` | `id=1` | | `startTime` | Start time of when Meeting was scheduled | `datetime` | `>`, `<`, `>=`, `<=` | `startTime>2025-01-01T01:00:00Z` | | `createdAt` | When the Meeting was created in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-01-01T01:00:00Z` | | `updatedAt` | When the Meeting was updated in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-01-01T01:00:00Z`| + * Get metadata on all Meetings + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + * @param [filter] Filter options + */ + public v2MeetingsGETWithHttpInfo(cursor?: string, limit?: number, filter?: string, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); + + const requestContextPromise = this.requestFactory.v2MeetingsGET(cursor, limit, filter, _config); + // build promise chain + let middlewarePreObservable = from(requestContextPromise); + for (const middleware of _config.middleware) { + middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); + } + + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). + pipe(mergeMap((response: ResponseContext) => { + let middlewarePostObservable = of(response); + for (const middleware of _config.middleware.reverse()) { + middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); + } + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2MeetingsGETWithHttpInfo(rsp))); + })); + } + + /** + * Paginate through all Meetings in Affinity. Returns basic information about past and future meeting interactions and its attendees. You can filter meetings using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|----------------------------------| | `id` | Unique identifier for Meetings | `int64` | `=` | `id=1` | | `startTime` | Start time of when Meeting was scheduled | `datetime` | `>`, `<`, `>=`, `<=` | `startTime>2025-01-01T01:00:00Z` | | `createdAt` | When the Meeting was created in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-01-01T01:00:00Z` | | `updatedAt` | When the Meeting was updated in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-01-01T01:00:00Z`| + * Get metadata on all Meetings + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + * @param [filter] Filter options + */ + public v2MeetingsGET(cursor?: string, limit?: number, filter?: string, _options?: ConfigurationOptions): Observable { + return this.v2MeetingsGETWithHttpInfo(cursor, limit, filter, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + } + +} + +import { NotesApiRequestFactory, NotesApiResponseProcessor} from "../apis/NotesApi.ts"; +export class ObservableNotesApi { + private requestFactory: NotesApiRequestFactory; + private responseProcessor: NotesApiResponseProcessor; + private configuration: Configuration; + + public constructor( + configuration: Configuration, + requestFactory?: NotesApiRequestFactory, + responseProcessor?: NotesApiResponseProcessor + ) { + this.configuration = configuration; + this.requestFactory = requestFactory || new NotesApiRequestFactory(configuration); + this.responseProcessor = responseProcessor || new NotesApiResponseProcessor(); + } + + /** + * | ⚠️ This endpoint is currently in BETA | |--| Returns all notes, with the exception of replies. You can filter notes using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|---------------------------------| | `id` | Filter notes by id | `int32` | `=` | `id=1` | | `creator.id` | Filter notes by the creator of the note | `int32` | `=` | `creator.id=1` | | `createdAt` | Filter notes by when it was created | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-02-04T10:48:24Z` | | `updatedAt` | Filter notes by when it was updated | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-02-03T10:48:24Z`| + * Get all Notes + * @param [totalCount] Include total count of the collection in the pagination response + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + * @param [filter] Filter options + * @param [includes] Additional properties to include in the response + */ + public v2NotesGETWithHttpInfo(totalCount?: boolean, cursor?: string, limit?: number, filter?: string, includes?: Set<'companiesPreview' | 'personsPreview' | 'opportunitiesPreview' | 'repliesCount'>, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); + + const requestContextPromise = this.requestFactory.v2NotesGET(totalCount, cursor, limit, filter, includes, _config); + // build promise chain + let middlewarePreObservable = from(requestContextPromise); + for (const middleware of _config.middleware) { + middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); + } + + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). + pipe(mergeMap((response: ResponseContext) => { + let middlewarePostObservable = of(response); + for (const middleware of _config.middleware.reverse()) { + middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); + } + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2NotesGETWithHttpInfo(rsp))); + })); + } + + /** + * | ⚠️ This endpoint is currently in BETA | |--| Returns all notes, with the exception of replies. You can filter notes using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|---------------------------------| | `id` | Filter notes by id | `int32` | `=` | `id=1` | | `creator.id` | Filter notes by the creator of the note | `int32` | `=` | `creator.id=1` | | `createdAt` | Filter notes by when it was created | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-02-04T10:48:24Z` | | `updatedAt` | Filter notes by when it was updated | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-02-03T10:48:24Z`| + * Get all Notes + * @param [totalCount] Include total count of the collection in the pagination response + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + * @param [filter] Filter options + * @param [includes] Additional properties to include in the response + */ + public v2NotesGET(totalCount?: boolean, cursor?: string, limit?: number, filter?: string, includes?: Set<'companiesPreview' | 'personsPreview' | 'opportunitiesPreview' | 'repliesCount'>, _options?: ConfigurationOptions): Observable { + return this.v2NotesGETWithHttpInfo(totalCount, cursor, limit, filter, includes, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + } + + /** + * | ⚠️ This endpoint is currently in BETA | |--| Returns directly attached companies for a given Note. + * Get Companies attached to a Note + * @param noteId The id of the Note to get attached Companies + * @param [totalCount] Include total count of the collection in the pagination response + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page */ - public getV2ListsListidSavedViewsViewidWithHttpInfo(listId: number, viewId: number, _options?: ConfigurationOptions): Observable> { - let _config = this.configuration; - let allMiddleware: Middleware[] = []; - if (_options && _options.middleware){ - const middlewareMergeStrategy = _options.middlewareMergeStrategy || 'replace' // default to replace behavior - // call-time middleware provided - const calltimeMiddleware: Middleware[] = _options.middleware; - - switch(middlewareMergeStrategy){ - case 'append': - allMiddleware = this.configuration.middleware.concat(calltimeMiddleware); - break; - case 'prepend': - allMiddleware = calltimeMiddleware.concat(this.configuration.middleware) - break; - case 'replace': - allMiddleware = calltimeMiddleware - break; - default: - throw new Error(`unrecognized middleware merge strategy '${middlewareMergeStrategy}'`) - } - } - if (_options){ - _config = { - baseServer: _options.baseServer || this.configuration.baseServer, - httpApi: _options.httpApi || this.configuration.httpApi, - authMethods: _options.authMethods || this.configuration.authMethods, - middleware: allMiddleware || this.configuration.middleware - }; - } - - const requestContextPromise = this.requestFactory.getV2ListsListidSavedViewsViewid(listId, viewId, _config); + public v2NotesNoteIdAttachedCompaniesGETWithHttpInfo(noteId: number, totalCount?: boolean, cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); + + const requestContextPromise = this.requestFactory.v2NotesNoteIdAttachedCompaniesGET(noteId, totalCount, cursor, limit, _config); // build promise chain let middlewarePreObservable = from(requestContextPromise); - for (const middleware of allMiddleware) { + for (const middleware of _config.middleware) { middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); } - return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => this.configuration.httpApi.send(ctx))). + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). pipe(mergeMap((response: ResponseContext) => { let middlewarePostObservable = of(response); - for (const middleware of allMiddleware.reverse()) { + for (const middleware of _config.middleware.reverse()) { middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); } - return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.getV2ListsListidSavedViewsViewidWithHttpInfo(rsp))); + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2NotesNoteIdAttachedCompaniesGETWithHttpInfo(rsp))); })); } /** - * Returns metadata on a single Saved View. - * Get metadata on a single Saved View - * @param listId List ID - * @param viewId Saved view ID + * | ⚠️ This endpoint is currently in BETA | |--| Returns directly attached companies for a given Note. + * Get Companies attached to a Note + * @param noteId The id of the Note to get attached Companies + * @param [totalCount] Include total count of the collection in the pagination response + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page */ - public getV2ListsListidSavedViewsViewid(listId: number, viewId: number, _options?: ConfigurationOptions): Observable { - return this.getV2ListsListidSavedViewsViewidWithHttpInfo(listId, viewId, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + public v2NotesNoteIdAttachedCompaniesGET(noteId: number, totalCount?: boolean, cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable { + return this.v2NotesNoteIdAttachedCompaniesGETWithHttpInfo(noteId, totalCount, cursor, limit, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); } /** - * Paginate through the List Entries (AKA rows) on a given Saved View. Use this endpoint when you need to filter entities or only want **some** field data to be returned: This endpoint respects the filters set on a Saved View via web app, and only returns field data corresponding to the columns that have been pulled into the Saved View via web app. Though this endpoint respects the Saved View\'s filters and column/Field selection, it does not yet preserve sort order. This endpoint also only supports **sheet-type Saved Views**, and not board- or dashboard-type Saved Views. See the [Data Model](#section/Data-Model) section for more information about Saved Views. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Get all List Entries on a Saved View - * @param listId List ID - * @param viewId Saved view ID + * | ⚠️ This endpoint is currently in BETA | |--| Returns directly attached opportunities for a given Note. + * Get Opportunities attached to a Note + * @param noteId The id of the Note to get attached Opportunities + * @param [totalCount] Include total count of the collection in the pagination response * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page */ - public getV2ListsListidSavedViewsViewidListEntriesWithHttpInfo(listId: number, viewId: number, cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable> { - let _config = this.configuration; - let allMiddleware: Middleware[] = []; - if (_options && _options.middleware){ - const middlewareMergeStrategy = _options.middlewareMergeStrategy || 'replace' // default to replace behavior - // call-time middleware provided - const calltimeMiddleware: Middleware[] = _options.middleware; - - switch(middlewareMergeStrategy){ - case 'append': - allMiddleware = this.configuration.middleware.concat(calltimeMiddleware); - break; - case 'prepend': - allMiddleware = calltimeMiddleware.concat(this.configuration.middleware) - break; - case 'replace': - allMiddleware = calltimeMiddleware - break; - default: - throw new Error(`unrecognized middleware merge strategy '${middlewareMergeStrategy}'`) - } - } - if (_options){ - _config = { - baseServer: _options.baseServer || this.configuration.baseServer, - httpApi: _options.httpApi || this.configuration.httpApi, - authMethods: _options.authMethods || this.configuration.authMethods, - middleware: allMiddleware || this.configuration.middleware - }; - } - - const requestContextPromise = this.requestFactory.getV2ListsListidSavedViewsViewidListEntries(listId, viewId, cursor, limit, _config); + public v2NotesNoteIdAttachedOpportunitiesGETWithHttpInfo(noteId: number, totalCount?: boolean, cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); + + const requestContextPromise = this.requestFactory.v2NotesNoteIdAttachedOpportunitiesGET(noteId, totalCount, cursor, limit, _config); // build promise chain let middlewarePreObservable = from(requestContextPromise); - for (const middleware of allMiddleware) { + for (const middleware of _config.middleware) { middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); } - return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => this.configuration.httpApi.send(ctx))). + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). pipe(mergeMap((response: ResponseContext) => { let middlewarePostObservable = of(response); - for (const middleware of allMiddleware.reverse()) { + for (const middleware of _config.middleware.reverse()) { middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); } - return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.getV2ListsListidSavedViewsViewidListEntriesWithHttpInfo(rsp))); + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2NotesNoteIdAttachedOpportunitiesGETWithHttpInfo(rsp))); })); } /** - * Paginate through the List Entries (AKA rows) on a given Saved View. Use this endpoint when you need to filter entities or only want **some** field data to be returned: This endpoint respects the filters set on a Saved View via web app, and only returns field data corresponding to the columns that have been pulled into the Saved View via web app. Though this endpoint respects the Saved View\'s filters and column/Field selection, it does not yet preserve sort order. This endpoint also only supports **sheet-type Saved Views**, and not board- or dashboard-type Saved Views. See the [Data Model](#section/Data-Model) section for more information about Saved Views. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Get all List Entries on a Saved View - * @param listId List ID - * @param viewId Saved view ID + * | ⚠️ This endpoint is currently in BETA | |--| Returns directly attached opportunities for a given Note. + * Get Opportunities attached to a Note + * @param noteId The id of the Note to get attached Opportunities + * @param [totalCount] Include total count of the collection in the pagination response * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page */ - public getV2ListsListidSavedViewsViewidListEntries(listId: number, viewId: number, cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable { - return this.getV2ListsListidSavedViewsViewidListEntriesWithHttpInfo(listId, viewId, cursor, limit, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + public v2NotesNoteIdAttachedOpportunitiesGET(noteId: number, totalCount?: boolean, cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable { + return this.v2NotesNoteIdAttachedOpportunitiesGETWithHttpInfo(noteId, totalCount, cursor, limit, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); } /** - * Returns metadata on Lists. - * Get metadata on all Lists + * | ⚠️ This endpoint is currently in BETA | |--| Returns directly attached persons for a given Note. + * Get Persons attached to a Note + * @param noteId The id of the Note to get attached Persons + * @param [totalCount] Include total count of the collection in the pagination response * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page */ - public v2ListsGETWithHttpInfo(cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable> { - let _config = this.configuration; - let allMiddleware: Middleware[] = []; - if (_options && _options.middleware){ - const middlewareMergeStrategy = _options.middlewareMergeStrategy || 'replace' // default to replace behavior - // call-time middleware provided - const calltimeMiddleware: Middleware[] = _options.middleware; - - switch(middlewareMergeStrategy){ - case 'append': - allMiddleware = this.configuration.middleware.concat(calltimeMiddleware); - break; - case 'prepend': - allMiddleware = calltimeMiddleware.concat(this.configuration.middleware) - break; - case 'replace': - allMiddleware = calltimeMiddleware - break; - default: - throw new Error(`unrecognized middleware merge strategy '${middlewareMergeStrategy}'`) - } - } - if (_options){ - _config = { - baseServer: _options.baseServer || this.configuration.baseServer, - httpApi: _options.httpApi || this.configuration.httpApi, - authMethods: _options.authMethods || this.configuration.authMethods, - middleware: allMiddleware || this.configuration.middleware - }; - } + public v2NotesNoteIdAttachedPersonsGETWithHttpInfo(noteId: number, totalCount?: boolean, cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); - const requestContextPromise = this.requestFactory.v2ListsGET(cursor, limit, _config); + const requestContextPromise = this.requestFactory.v2NotesNoteIdAttachedPersonsGET(noteId, totalCount, cursor, limit, _config); // build promise chain let middlewarePreObservable = from(requestContextPromise); - for (const middleware of allMiddleware) { + for (const middleware of _config.middleware) { middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); } - return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => this.configuration.httpApi.send(ctx))). + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). pipe(mergeMap((response: ResponseContext) => { let middlewarePostObservable = of(response); - for (const middleware of allMiddleware.reverse()) { + for (const middleware of _config.middleware.reverse()) { middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); } - return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2ListsGETWithHttpInfo(rsp))); + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2NotesNoteIdAttachedPersonsGETWithHttpInfo(rsp))); })); } /** - * Returns metadata on Lists. - * Get metadata on all Lists + * | ⚠️ This endpoint is currently in BETA | |--| Returns directly attached persons for a given Note. + * Get Persons attached to a Note + * @param noteId The id of the Note to get attached Persons + * @param [totalCount] Include total count of the collection in the pagination response * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page */ - public v2ListsGET(cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable { - return this.v2ListsGETWithHttpInfo(cursor, limit, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + public v2NotesNoteIdAttachedPersonsGET(noteId: number, totalCount?: boolean, cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable { + return this.v2NotesNoteIdAttachedPersonsGETWithHttpInfo(noteId, totalCount, cursor, limit, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); } /** - * Returns metadata on the Fields available on a single List. Use the returned Field IDs to request field data from the GET `/v2/lists/{listId}/list-entries` endpoint. - * Get metadata on a single List\'s Fields - * @param listId List ID - * @param [cursor] Cursor for the next or previous page - * @param [limit] Number of items to include in the page + * | ⚠️ This endpoint is currently in BETA | |--| Get a Note with a given id + * Get a single Note + * @param noteId The id of the Note + * @param [includes] Additional properties to include in the response */ - public v2ListsListIdFieldsGETWithHttpInfo(listId: number, cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable> { - let _config = this.configuration; - let allMiddleware: Middleware[] = []; - if (_options && _options.middleware){ - const middlewareMergeStrategy = _options.middlewareMergeStrategy || 'replace' // default to replace behavior - // call-time middleware provided - const calltimeMiddleware: Middleware[] = _options.middleware; - - switch(middlewareMergeStrategy){ - case 'append': - allMiddleware = this.configuration.middleware.concat(calltimeMiddleware); - break; - case 'prepend': - allMiddleware = calltimeMiddleware.concat(this.configuration.middleware) - break; - case 'replace': - allMiddleware = calltimeMiddleware - break; - default: - throw new Error(`unrecognized middleware merge strategy '${middlewareMergeStrategy}'`) - } - } - if (_options){ - _config = { - baseServer: _options.baseServer || this.configuration.baseServer, - httpApi: _options.httpApi || this.configuration.httpApi, - authMethods: _options.authMethods || this.configuration.authMethods, - middleware: allMiddleware || this.configuration.middleware - }; - } + public v2NotesNoteIdGETWithHttpInfo(noteId: number, includes?: Set<'companiesPreview' | 'personsPreview' | 'opportunitiesPreview' | 'repliesCount'>, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); - const requestContextPromise = this.requestFactory.v2ListsListIdFieldsGET(listId, cursor, limit, _config); + const requestContextPromise = this.requestFactory.v2NotesNoteIdGET(noteId, includes, _config); // build promise chain let middlewarePreObservable = from(requestContextPromise); - for (const middleware of allMiddleware) { + for (const middleware of _config.middleware) { middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); } - return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => this.configuration.httpApi.send(ctx))). + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). pipe(mergeMap((response: ResponseContext) => { let middlewarePostObservable = of(response); - for (const middleware of allMiddleware.reverse()) { + for (const middleware of _config.middleware.reverse()) { middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); } - return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2ListsListIdFieldsGETWithHttpInfo(rsp))); + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2NotesNoteIdGETWithHttpInfo(rsp))); })); } /** - * Returns metadata on the Fields available on a single List. Use the returned Field IDs to request field data from the GET `/v2/lists/{listId}/list-entries` endpoint. - * Get metadata on a single List\'s Fields - * @param listId List ID - * @param [cursor] Cursor for the next or previous page - * @param [limit] Number of items to include in the page + * | ⚠️ This endpoint is currently in BETA | |--| Get a Note with a given id + * Get a single Note + * @param noteId The id of the Note + * @param [includes] Additional properties to include in the response */ - public v2ListsListIdFieldsGET(listId: number, cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable { - return this.v2ListsListIdFieldsGETWithHttpInfo(listId, cursor, limit, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + public v2NotesNoteIdGET(noteId: number, includes?: Set<'companiesPreview' | 'personsPreview' | 'opportunitiesPreview' | 'repliesCount'>, _options?: ConfigurationOptions): Observable { + return this.v2NotesNoteIdGETWithHttpInfo(noteId, includes, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); } /** - * Returns metadata on a single List. - * Get metadata on a single List - * @param listId List ID + * | ⚠️ This endpoint is currently in BETA | |--| This endpoint returns reply notes for a given note id. You can filter replies using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|---------------------------------| | `creator.id` | Filter notes by the creator of the note | `int32` | `=` | `creator.id=1` | | `createdAt` | Filter notes by when it was created | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-02-04T10:48:24Z` | | `updatedAt` | Filter notes by when it was updated | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-02-03T10:48:24Z`| + * Get replies for a Note + * @param noteId Note ID + * @param [filter] Filter options + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + * @param [totalCount] Include total count of the collection in the pagination response */ - public v2ListsListIdGETWithHttpInfo(listId: number, _options?: ConfigurationOptions): Observable> { - let _config = this.configuration; - let allMiddleware: Middleware[] = []; - if (_options && _options.middleware){ - const middlewareMergeStrategy = _options.middlewareMergeStrategy || 'replace' // default to replace behavior - // call-time middleware provided - const calltimeMiddleware: Middleware[] = _options.middleware; - - switch(middlewareMergeStrategy){ - case 'append': - allMiddleware = this.configuration.middleware.concat(calltimeMiddleware); - break; - case 'prepend': - allMiddleware = calltimeMiddleware.concat(this.configuration.middleware) - break; - case 'replace': - allMiddleware = calltimeMiddleware - break; - default: - throw new Error(`unrecognized middleware merge strategy '${middlewareMergeStrategy}'`) - } - } - if (_options){ - _config = { - baseServer: _options.baseServer || this.configuration.baseServer, - httpApi: _options.httpApi || this.configuration.httpApi, - authMethods: _options.authMethods || this.configuration.authMethods, - middleware: allMiddleware || this.configuration.middleware - }; - } + public v2NotesNoteIdRepliesGETWithHttpInfo(noteId: number, filter?: string, cursor?: string, limit?: number, totalCount?: boolean, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); - const requestContextPromise = this.requestFactory.v2ListsListIdGET(listId, _config); + const requestContextPromise = this.requestFactory.v2NotesNoteIdRepliesGET(noteId, filter, cursor, limit, totalCount, _config); // build promise chain let middlewarePreObservable = from(requestContextPromise); - for (const middleware of allMiddleware) { + for (const middleware of _config.middleware) { middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); } - return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => this.configuration.httpApi.send(ctx))). + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). pipe(mergeMap((response: ResponseContext) => { let middlewarePostObservable = of(response); - for (const middleware of allMiddleware.reverse()) { + for (const middleware of _config.middleware.reverse()) { middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); } - return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2ListsListIdGETWithHttpInfo(rsp))); + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2NotesNoteIdRepliesGETWithHttpInfo(rsp))); })); } /** - * Returns metadata on a single List. - * Get metadata on a single List - * @param listId List ID + * | ⚠️ This endpoint is currently in BETA | |--| This endpoint returns reply notes for a given note id. You can filter replies using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|---------------------------------| | `creator.id` | Filter notes by the creator of the note | `int32` | `=` | `creator.id=1` | | `createdAt` | Filter notes by when it was created | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-02-04T10:48:24Z` | | `updatedAt` | Filter notes by when it was updated | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-02-03T10:48:24Z`| + * Get replies for a Note + * @param noteId Note ID + * @param [filter] Filter options + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + * @param [totalCount] Include total count of the collection in the pagination response */ - public v2ListsListIdGET(listId: number, _options?: ConfigurationOptions): Observable { - return this.v2ListsListIdGETWithHttpInfo(listId, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + public v2NotesNoteIdRepliesGET(noteId: number, filter?: string, cursor?: string, limit?: number, totalCount?: boolean, _options?: ConfigurationOptions): Observable { + return this.v2NotesNoteIdRepliesGETWithHttpInfo(noteId, filter, cursor, limit, totalCount, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + } + +} + +import { OpportunitiesApiRequestFactory, OpportunitiesApiResponseProcessor} from "../apis/OpportunitiesApi.ts"; +export class ObservableOpportunitiesApi { + private requestFactory: OpportunitiesApiRequestFactory; + private responseProcessor: OpportunitiesApiResponseProcessor; + private configuration: Configuration; + + public constructor( + configuration: Configuration, + requestFactory?: OpportunitiesApiRequestFactory, + responseProcessor?: OpportunitiesApiResponseProcessor + ) { + this.configuration = configuration; + this.requestFactory = requestFactory || new OpportunitiesApiRequestFactory(configuration); + this.responseProcessor = responseProcessor || new OpportunitiesApiResponseProcessor(); } /** - * Paginate through the List Entries (AKA rows) on a given List. Returns basic information and field data, including list-specific field data, on each Company, Person, or Opportunity on the List. List Entries also include metadata about their creation, i.e., when they were added to the List and by whom. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/lists/{listId}/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, List Entries will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Get all List Entries on a List - * @param listId List ID + * Paginate through Opportunities in Affinity. Returns basic information but **not** field data on each Opportunity. To access field data on Opportunities, use the `/lists/{list_id}/list-entries` or the `/v2/lists/{list_id}/saved-views/{view_id}/list-entries` GET endpoint. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Get all Opportunities * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page - * @param [fieldIds] Field IDs for which to return field data - * @param [fieldTypes] Field Types for which to return field data + * @param [ids] Opportunity IDs */ - public v2ListsListIdListEntriesGETWithHttpInfo(listId: number, cursor?: string, limit?: number, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'list' | 'relationship-intelligence'>, _options?: ConfigurationOptions): Observable> { - let _config = this.configuration; - let allMiddleware: Middleware[] = []; - if (_options && _options.middleware){ - const middlewareMergeStrategy = _options.middlewareMergeStrategy || 'replace' // default to replace behavior - // call-time middleware provided - const calltimeMiddleware: Middleware[] = _options.middleware; - - switch(middlewareMergeStrategy){ - case 'append': - allMiddleware = this.configuration.middleware.concat(calltimeMiddleware); - break; - case 'prepend': - allMiddleware = calltimeMiddleware.concat(this.configuration.middleware) - break; - case 'replace': - allMiddleware = calltimeMiddleware - break; - default: - throw new Error(`unrecognized middleware merge strategy '${middlewareMergeStrategy}'`) - } - } - if (_options){ - _config = { - baseServer: _options.baseServer || this.configuration.baseServer, - httpApi: _options.httpApi || this.configuration.httpApi, - authMethods: _options.authMethods || this.configuration.authMethods, - middleware: allMiddleware || this.configuration.middleware - }; - } + public v2OpportunitiesGETWithHttpInfo(cursor?: string, limit?: number, ids?: Array, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); - const requestContextPromise = this.requestFactory.v2ListsListIdListEntriesGET(listId, cursor, limit, fieldIds, fieldTypes, _config); + const requestContextPromise = this.requestFactory.v2OpportunitiesGET(cursor, limit, ids, _config); // build promise chain let middlewarePreObservable = from(requestContextPromise); - for (const middleware of allMiddleware) { + for (const middleware of _config.middleware) { middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); } - return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => this.configuration.httpApi.send(ctx))). + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). pipe(mergeMap((response: ResponseContext) => { let middlewarePostObservable = of(response); - for (const middleware of allMiddleware.reverse()) { + for (const middleware of _config.middleware.reverse()) { middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); } - return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2ListsListIdListEntriesGETWithHttpInfo(rsp))); + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2OpportunitiesGETWithHttpInfo(rsp))); })); } /** - * Paginate through the List Entries (AKA rows) on a given List. Returns basic information and field data, including list-specific field data, on each Company, Person, or Opportunity on the List. List Entries also include metadata about their creation, i.e., when they were added to the List and by whom. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/lists/{listId}/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, List Entries will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Get all List Entries on a List - * @param listId List ID + * Paginate through Opportunities in Affinity. Returns basic information but **not** field data on each Opportunity. To access field data on Opportunities, use the `/lists/{list_id}/list-entries` or the `/v2/lists/{list_id}/saved-views/{view_id}/list-entries` GET endpoint. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Get all Opportunities * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page - * @param [fieldIds] Field IDs for which to return field data - * @param [fieldTypes] Field Types for which to return field data + * @param [ids] Opportunity IDs */ - public v2ListsListIdListEntriesGET(listId: number, cursor?: string, limit?: number, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'list' | 'relationship-intelligence'>, _options?: ConfigurationOptions): Observable { - return this.v2ListsListIdListEntriesGETWithHttpInfo(listId, cursor, limit, fieldIds, fieldTypes, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + public v2OpportunitiesGET(cursor?: string, limit?: number, ids?: Array, _options?: ConfigurationOptions): Observable { + return this.v2OpportunitiesGETWithHttpInfo(cursor, limit, ids, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); } /** - * | ⚠️ This endpoint is currently in BETA | |--| Returns a single field value on a list entry. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Get a single field value [BETA] - * @param listId List ID - * @param listEntryId List Entry ID - * @param fieldId Field ID + * Returns basic information but **not** field data on the requested Opportunity. To access field data on Opportunities, use the `/lists/{list_id}/list-entries` or the `/v2/lists/{list_id}/saved-views/{view_id}/list-entries` GET endpoint. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Get a single Opportunity + * @param opportunityId Opportunity ID */ - public v2ListsListIdListEntriesListEntryIdFieldsFieldIdGETWithHttpInfo(listId: number, listEntryId: number, fieldId: string, _options?: ConfigurationOptions): Observable> { - let _config = this.configuration; - let allMiddleware: Middleware[] = []; - if (_options && _options.middleware){ - const middlewareMergeStrategy = _options.middlewareMergeStrategy || 'replace' // default to replace behavior - // call-time middleware provided - const calltimeMiddleware: Middleware[] = _options.middleware; - - switch(middlewareMergeStrategy){ - case 'append': - allMiddleware = this.configuration.middleware.concat(calltimeMiddleware); - break; - case 'prepend': - allMiddleware = calltimeMiddleware.concat(this.configuration.middleware) - break; - case 'replace': - allMiddleware = calltimeMiddleware - break; - default: - throw new Error(`unrecognized middleware merge strategy '${middlewareMergeStrategy}'`) - } - } - if (_options){ - _config = { - baseServer: _options.baseServer || this.configuration.baseServer, - httpApi: _options.httpApi || this.configuration.httpApi, - authMethods: _options.authMethods || this.configuration.authMethods, - middleware: allMiddleware || this.configuration.middleware - }; - } + public v2OpportunitiesOpportunityIdGETWithHttpInfo(opportunityId: number, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); - const requestContextPromise = this.requestFactory.v2ListsListIdListEntriesListEntryIdFieldsFieldIdGET(listId, listEntryId, fieldId, _config); + const requestContextPromise = this.requestFactory.v2OpportunitiesOpportunityIdGET(opportunityId, _config); // build promise chain let middlewarePreObservable = from(requestContextPromise); - for (const middleware of allMiddleware) { + for (const middleware of _config.middleware) { middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); } - return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => this.configuration.httpApi.send(ctx))). + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). pipe(mergeMap((response: ResponseContext) => { let middlewarePostObservable = of(response); - for (const middleware of allMiddleware.reverse()) { + for (const middleware of _config.middleware.reverse()) { middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); } - return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2ListsListIdListEntriesListEntryIdFieldsFieldIdGETWithHttpInfo(rsp))); + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2OpportunitiesOpportunityIdGETWithHttpInfo(rsp))); })); } /** - * | ⚠️ This endpoint is currently in BETA | |--| Returns a single field value on a list entry. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Get a single field value [BETA] - * @param listId List ID - * @param listEntryId List Entry ID - * @param fieldId Field ID + * Returns basic information but **not** field data on the requested Opportunity. To access field data on Opportunities, use the `/lists/{list_id}/list-entries` or the `/v2/lists/{list_id}/saved-views/{view_id}/list-entries` GET endpoint. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Get a single Opportunity + * @param opportunityId Opportunity ID */ - public v2ListsListIdListEntriesListEntryIdFieldsFieldIdGET(listId: number, listEntryId: number, fieldId: string, _options?: ConfigurationOptions): Observable { - return this.v2ListsListIdListEntriesListEntryIdFieldsFieldIdGETWithHttpInfo(listId, listEntryId, fieldId, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + public v2OpportunitiesOpportunityIdGET(opportunityId: number, _options?: ConfigurationOptions): Observable { + return this.v2OpportunitiesOpportunityIdGETWithHttpInfo(opportunityId, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); } /** - * | ⚠️ This endpoint is currently in BETA | |--| Update a single field value. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Update a single field value on a List Entry [BETA] - * @param listId List ID - * @param listEntryId List Entry ID - * @param fieldId Field ID - * @param fieldUpdate + * | ⚠️ This endpoint is currently in BETA | |--| Returns Notes for a given Opportunity which includes directly attached notes and those attached to persons on this Opportunity. You can filter notes using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|---------------------------------| | `creator.id` | Filter notes by the creator of the note | `int32` | `=` | `creator.id=1` | | `createdAt` | Filter notes by when it was created | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-02-04T10:48:24Z` | | `updatedAt` | Filter notes by when it was updated | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-02-03T10:48:24Z`| + * Get Notes for an Opportunity + * @param opportunityId Opportunity ID + * @param [filter] Filter options + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + * @param [totalCount] Include total count of the collection in the pagination response */ - public v2ListsListIdListEntriesListEntryIdFieldsFieldIdPOSTWithHttpInfo(listId: number, listEntryId: number, fieldId: string, fieldUpdate: FieldUpdate, _options?: ConfigurationOptions): Observable> { - let _config = this.configuration; - let allMiddleware: Middleware[] = []; - if (_options && _options.middleware){ - const middlewareMergeStrategy = _options.middlewareMergeStrategy || 'replace' // default to replace behavior - // call-time middleware provided - const calltimeMiddleware: Middleware[] = _options.middleware; - - switch(middlewareMergeStrategy){ - case 'append': - allMiddleware = this.configuration.middleware.concat(calltimeMiddleware); - break; - case 'prepend': - allMiddleware = calltimeMiddleware.concat(this.configuration.middleware) - break; - case 'replace': - allMiddleware = calltimeMiddleware - break; - default: - throw new Error(`unrecognized middleware merge strategy '${middlewareMergeStrategy}'`) - } - } - if (_options){ - _config = { - baseServer: _options.baseServer || this.configuration.baseServer, - httpApi: _options.httpApi || this.configuration.httpApi, - authMethods: _options.authMethods || this.configuration.authMethods, - middleware: allMiddleware || this.configuration.middleware - }; - } + public v2OpportunitiesOpportunityIdNotesGETWithHttpInfo(opportunityId: number, filter?: string, cursor?: string, limit?: number, totalCount?: boolean, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); - const requestContextPromise = this.requestFactory.v2ListsListIdListEntriesListEntryIdFieldsFieldIdPOST(listId, listEntryId, fieldId, fieldUpdate, _config); + const requestContextPromise = this.requestFactory.v2OpportunitiesOpportunityIdNotesGET(opportunityId, filter, cursor, limit, totalCount, _config); // build promise chain let middlewarePreObservable = from(requestContextPromise); - for (const middleware of allMiddleware) { + for (const middleware of _config.middleware) { middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); } - return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => this.configuration.httpApi.send(ctx))). + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). pipe(mergeMap((response: ResponseContext) => { let middlewarePostObservable = of(response); - for (const middleware of allMiddleware.reverse()) { + for (const middleware of _config.middleware.reverse()) { middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); } - return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2ListsListIdListEntriesListEntryIdFieldsFieldIdPOSTWithHttpInfo(rsp))); + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2OpportunitiesOpportunityIdNotesGETWithHttpInfo(rsp))); })); } /** - * | ⚠️ This endpoint is currently in BETA | |--| Update a single field value. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Update a single field value on a List Entry [BETA] - * @param listId List ID - * @param listEntryId List Entry ID - * @param fieldId Field ID - * @param fieldUpdate + * | ⚠️ This endpoint is currently in BETA | |--| Returns Notes for a given Opportunity which includes directly attached notes and those attached to persons on this Opportunity. You can filter notes using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|---------------------------------| | `creator.id` | Filter notes by the creator of the note | `int32` | `=` | `creator.id=1` | | `createdAt` | Filter notes by when it was created | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-02-04T10:48:24Z` | | `updatedAt` | Filter notes by when it was updated | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-02-03T10:48:24Z`| + * Get Notes for an Opportunity + * @param opportunityId Opportunity ID + * @param [filter] Filter options + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + * @param [totalCount] Include total count of the collection in the pagination response */ - public v2ListsListIdListEntriesListEntryIdFieldsFieldIdPOST(listId: number, listEntryId: number, fieldId: string, fieldUpdate: FieldUpdate, _options?: ConfigurationOptions): Observable { - return this.v2ListsListIdListEntriesListEntryIdFieldsFieldIdPOSTWithHttpInfo(listId, listEntryId, fieldId, fieldUpdate, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + public v2OpportunitiesOpportunityIdNotesGET(opportunityId: number, filter?: string, cursor?: string, limit?: number, totalCount?: boolean, _options?: ConfigurationOptions): Observable { + return this.v2OpportunitiesOpportunityIdNotesGETWithHttpInfo(opportunityId, filter, cursor, limit, totalCount, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + } + +} + +import { PersonMergesApiRequestFactory, PersonMergesApiResponseProcessor} from "../apis/PersonMergesApi.ts"; +export class ObservablePersonMergesApi { + private requestFactory: PersonMergesApiRequestFactory; + private responseProcessor: PersonMergesApiResponseProcessor; + private configuration: Configuration; + + public constructor( + configuration: Configuration, + requestFactory?: PersonMergesApiRequestFactory, + responseProcessor?: PersonMergesApiResponseProcessor + ) { + this.configuration = configuration; + this.requestFactory = requestFactory || new PersonMergesApiRequestFactory(configuration); + this.responseProcessor = responseProcessor || new PersonMergesApiResponseProcessor(); } /** - * | ⚠️ This endpoint is currently in BETA | |--| Paginate through all field values on a single list entry. All fields will be included by default. The `ids` and `types` parameters can be used to filter the collection. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Get field values on a single List Entry [BETA] - * @param listId List ID - * @param listEntryId List Entry ID - * @param [ids] Field IDs for which to return field data - * @param [types] Field Types for which to return field data + * Retrieve paginated person merges for the organization. Returns all person merges initiated by users in your organization, including their current status, the persons involved, and merge details. You can filter person merges using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties: | Property | Type | Operators | Values | Examples | |----------|------|-----------|--------|----------| | `status` | `enum` | `=` | `in-progress`, `success`, `failed` | `status=failed` | | `taskId` | `string` | `=` | | `taskId=789e0123-e45b-67c8-d901-234567890123` | Person merges are returned in reverse chronological order (most recent first). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get All Person Merges * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page + * @param [filter] Filter person merges using Affinity Filtering Language */ - public v2ListsListIdListEntriesListEntryIdFieldsGETWithHttpInfo(listId: number, listEntryId: number, ids?: Array, types?: Array<'enriched' | 'global' | 'list' | 'relationship-intelligence'>, cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable> { - let _config = this.configuration; - let allMiddleware: Middleware[] = []; - if (_options && _options.middleware){ - const middlewareMergeStrategy = _options.middlewareMergeStrategy || 'replace' // default to replace behavior - // call-time middleware provided - const calltimeMiddleware: Middleware[] = _options.middleware; - - switch(middlewareMergeStrategy){ - case 'append': - allMiddleware = this.configuration.middleware.concat(calltimeMiddleware); - break; - case 'prepend': - allMiddleware = calltimeMiddleware.concat(this.configuration.middleware) - break; - case 'replace': - allMiddleware = calltimeMiddleware - break; - default: - throw new Error(`unrecognized middleware merge strategy '${middlewareMergeStrategy}'`) - } - } - if (_options){ - _config = { - baseServer: _options.baseServer || this.configuration.baseServer, - httpApi: _options.httpApi || this.configuration.httpApi, - authMethods: _options.authMethods || this.configuration.authMethods, - middleware: allMiddleware || this.configuration.middleware - }; - } + public v2PersonMergesGETWithHttpInfo(cursor?: string, limit?: number, filter?: string, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); - const requestContextPromise = this.requestFactory.v2ListsListIdListEntriesListEntryIdFieldsGET(listId, listEntryId, ids, types, cursor, limit, _config); + const requestContextPromise = this.requestFactory.v2PersonMergesGET(cursor, limit, filter, _config); // build promise chain let middlewarePreObservable = from(requestContextPromise); - for (const middleware of allMiddleware) { + for (const middleware of _config.middleware) { middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); } - return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => this.configuration.httpApi.send(ctx))). + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). pipe(mergeMap((response: ResponseContext) => { let middlewarePostObservable = of(response); - for (const middleware of allMiddleware.reverse()) { + for (const middleware of _config.middleware.reverse()) { middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); } - return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2ListsListIdListEntriesListEntryIdFieldsGETWithHttpInfo(rsp))); + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2PersonMergesGETWithHttpInfo(rsp))); })); } /** - * | ⚠️ This endpoint is currently in BETA | |--| Paginate through all field values on a single list entry. All fields will be included by default. The `ids` and `types` parameters can be used to filter the collection. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Get field values on a single List Entry [BETA] - * @param listId List ID - * @param listEntryId List Entry ID - * @param [ids] Field IDs for which to return field data - * @param [types] Field Types for which to return field data + * Retrieve paginated person merges for the organization. Returns all person merges initiated by users in your organization, including their current status, the persons involved, and merge details. You can filter person merges using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties: | Property | Type | Operators | Values | Examples | |----------|------|-----------|--------|----------| | `status` | `enum` | `=` | `in-progress`, `success`, `failed` | `status=failed` | | `taskId` | `string` | `=` | | `taskId=789e0123-e45b-67c8-d901-234567890123` | Person merges are returned in reverse chronological order (most recent first). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get All Person Merges * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page + * @param [filter] Filter person merges using Affinity Filtering Language */ - public v2ListsListIdListEntriesListEntryIdFieldsGET(listId: number, listEntryId: number, ids?: Array, types?: Array<'enriched' | 'global' | 'list' | 'relationship-intelligence'>, cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable { - return this.v2ListsListIdListEntriesListEntryIdFieldsGETWithHttpInfo(listId, listEntryId, ids, types, cursor, limit, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + public v2PersonMergesGET(cursor?: string, limit?: number, filter?: string, _options?: ConfigurationOptions): Observable { + return this.v2PersonMergesGETWithHttpInfo(cursor, limit, filter, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); } /** - * | ⚠️ This endpoint is currently in BETA | |--| Perform batch operations on a list entry\'s fields. Currently the only operation at the endpoint is `update-fields`, which allows you to update multiple field values with a single request. This is equivalent to calling [the single field update](#operation/v2_lists_listId_list-entries_listEntryId_fields_fieldId__POST) endpoint multiple times. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Perform batch operations on a list entry\'s fields [BETA] - * @param listId List ID - * @param listEntryId List Entry ID - * @param body + * Retrieve the status and details of a specific person merge. Returns information about the person merge including its current status, the persons involved, timestamps, and any error information if the merge failed. The `mergeId` can be obtained from the response of the [Get All Person Merges](#tag/personMerges/operation/v2_person-merges__GET) endpoint, or by filtering person merges by task ID using `/v2/person-merges?filter=taskId={taskId}` after initiating a merge. Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get Person Merge + * @param mergeId Person merge ID */ - public v2ListsListIdListEntriesListEntryIdFieldsPATCHWithHttpInfo(listId: number, listEntryId: number, body: ListEntryBatchOperationUpdateFields, _options?: ConfigurationOptions): Observable> { - let _config = this.configuration; - let allMiddleware: Middleware[] = []; - if (_options && _options.middleware){ - const middlewareMergeStrategy = _options.middlewareMergeStrategy || 'replace' // default to replace behavior - // call-time middleware provided - const calltimeMiddleware: Middleware[] = _options.middleware; - - switch(middlewareMergeStrategy){ - case 'append': - allMiddleware = this.configuration.middleware.concat(calltimeMiddleware); - break; - case 'prepend': - allMiddleware = calltimeMiddleware.concat(this.configuration.middleware) - break; - case 'replace': - allMiddleware = calltimeMiddleware - break; - default: - throw new Error(`unrecognized middleware merge strategy '${middlewareMergeStrategy}'`) - } - } - if (_options){ - _config = { - baseServer: _options.baseServer || this.configuration.baseServer, - httpApi: _options.httpApi || this.configuration.httpApi, - authMethods: _options.authMethods || this.configuration.authMethods, - middleware: allMiddleware || this.configuration.middleware - }; - } + public v2PersonMergesMergeIdGETWithHttpInfo(mergeId: number, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); - const requestContextPromise = this.requestFactory.v2ListsListIdListEntriesListEntryIdFieldsPATCH(listId, listEntryId, body, _config); + const requestContextPromise = this.requestFactory.v2PersonMergesMergeIdGET(mergeId, _config); // build promise chain let middlewarePreObservable = from(requestContextPromise); - for (const middleware of allMiddleware) { + for (const middleware of _config.middleware) { middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); } - return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => this.configuration.httpApi.send(ctx))). + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). pipe(mergeMap((response: ResponseContext) => { let middlewarePostObservable = of(response); - for (const middleware of allMiddleware.reverse()) { + for (const middleware of _config.middleware.reverse()) { middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); } - return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2ListsListIdListEntriesListEntryIdFieldsPATCHWithHttpInfo(rsp))); + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2PersonMergesMergeIdGETWithHttpInfo(rsp))); })); } /** - * | ⚠️ This endpoint is currently in BETA | |--| Perform batch operations on a list entry\'s fields. Currently the only operation at the endpoint is `update-fields`, which allows you to update multiple field values with a single request. This is equivalent to calling [the single field update](#operation/v2_lists_listId_list-entries_listEntryId_fields_fieldId__POST) endpoint multiple times. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Perform batch operations on a list entry\'s fields [BETA] - * @param listId List ID - * @param listEntryId List Entry ID - * @param body + * Retrieve the status and details of a specific person merge. Returns information about the person merge including its current status, the persons involved, timestamps, and any error information if the merge failed. The `mergeId` can be obtained from the response of the [Get All Person Merges](#tag/personMerges/operation/v2_person-merges__GET) endpoint, or by filtering person merges by task ID using `/v2/person-merges?filter=taskId={taskId}` after initiating a merge. Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get Person Merge + * @param mergeId Person merge ID */ - public v2ListsListIdListEntriesListEntryIdFieldsPATCH(listId: number, listEntryId: number, body: ListEntryBatchOperationUpdateFields, _options?: ConfigurationOptions): Observable { - return this.v2ListsListIdListEntriesListEntryIdFieldsPATCHWithHttpInfo(listId, listEntryId, body, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + public v2PersonMergesMergeIdGET(mergeId: number, _options?: ConfigurationOptions): Observable { + return this.v2PersonMergesMergeIdGETWithHttpInfo(mergeId, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); } /** - * | ⚠️ This endpoint is currently in BETA | |--| Retrieve a single list entry. Returns basic information and field data, including list-specific field data. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/lists/{listId}/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, the List Entry will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Get a single List Entry on a List [BETA] - * @param listId List ID - * @param listEntryId List Entry ID - * @param [fieldIds] Field IDs for which to return field data - * @param [fieldTypes] Field Types for which to return field data + * Initiate a person merge to combine a duplicate person profile into a primary person profile. This is an asynchronous process that will merge all data from the duplicate person into the primary person. Once the merge is initiated, you can track its progress using the returned [task URL](#tag/personMerges/operation/v2_tasks_person-merges_taskId__GET). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Initiate Person Merge + * @param personMergeRequest */ - public v2ListsListIdListEntriesListEntryIdGETWithHttpInfo(listId: number, listEntryId: number, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'list' | 'relationship-intelligence'>, _options?: ConfigurationOptions): Observable> { - let _config = this.configuration; - let allMiddleware: Middleware[] = []; - if (_options && _options.middleware){ - const middlewareMergeStrategy = _options.middlewareMergeStrategy || 'replace' // default to replace behavior - // call-time middleware provided - const calltimeMiddleware: Middleware[] = _options.middleware; - - switch(middlewareMergeStrategy){ - case 'append': - allMiddleware = this.configuration.middleware.concat(calltimeMiddleware); - break; - case 'prepend': - allMiddleware = calltimeMiddleware.concat(this.configuration.middleware) - break; - case 'replace': - allMiddleware = calltimeMiddleware - break; - default: - throw new Error(`unrecognized middleware merge strategy '${middlewareMergeStrategy}'`) - } - } - if (_options){ - _config = { - baseServer: _options.baseServer || this.configuration.baseServer, - httpApi: _options.httpApi || this.configuration.httpApi, - authMethods: _options.authMethods || this.configuration.authMethods, - middleware: allMiddleware || this.configuration.middleware - }; - } + public v2PersonMergesPOSTWithHttpInfo(personMergeRequest: PersonMergeRequest, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); - const requestContextPromise = this.requestFactory.v2ListsListIdListEntriesListEntryIdGET(listId, listEntryId, fieldIds, fieldTypes, _config); + const requestContextPromise = this.requestFactory.v2PersonMergesPOST(personMergeRequest, _config); // build promise chain let middlewarePreObservable = from(requestContextPromise); - for (const middleware of allMiddleware) { + for (const middleware of _config.middleware) { middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); } - return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => this.configuration.httpApi.send(ctx))). + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). pipe(mergeMap((response: ResponseContext) => { let middlewarePostObservable = of(response); - for (const middleware of allMiddleware.reverse()) { + for (const middleware of _config.middleware.reverse()) { middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); } - return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2ListsListIdListEntriesListEntryIdGETWithHttpInfo(rsp))); + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2PersonMergesPOSTWithHttpInfo(rsp))); })); } /** - * | ⚠️ This endpoint is currently in BETA | |--| Retrieve a single list entry. Returns basic information and field data, including list-specific field data. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/lists/{listId}/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, the List Entry will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Get a single List Entry on a List [BETA] - * @param listId List ID - * @param listEntryId List Entry ID - * @param [fieldIds] Field IDs for which to return field data - * @param [fieldTypes] Field Types for which to return field data + * Initiate a person merge to combine a duplicate person profile into a primary person profile. This is an asynchronous process that will merge all data from the duplicate person into the primary person. Once the merge is initiated, you can track its progress using the returned [task URL](#tag/personMerges/operation/v2_tasks_person-merges_taskId__GET). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Initiate Person Merge + * @param personMergeRequest */ - public v2ListsListIdListEntriesListEntryIdGET(listId: number, listEntryId: number, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'list' | 'relationship-intelligence'>, _options?: ConfigurationOptions): Observable { - return this.v2ListsListIdListEntriesListEntryIdGETWithHttpInfo(listId, listEntryId, fieldIds, fieldTypes, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); - } - -} - -import { OpportunitiesApiRequestFactory, OpportunitiesApiResponseProcessor} from "../apis/OpportunitiesApi.ts"; -export class ObservableOpportunitiesApi { - private requestFactory: OpportunitiesApiRequestFactory; - private responseProcessor: OpportunitiesApiResponseProcessor; - private configuration: Configuration; - - public constructor( - configuration: Configuration, - requestFactory?: OpportunitiesApiRequestFactory, - responseProcessor?: OpportunitiesApiResponseProcessor - ) { - this.configuration = configuration; - this.requestFactory = requestFactory || new OpportunitiesApiRequestFactory(configuration); - this.responseProcessor = responseProcessor || new OpportunitiesApiResponseProcessor(); + public v2PersonMergesPOST(personMergeRequest: PersonMergeRequest, _options?: ConfigurationOptions): Observable { + return this.v2PersonMergesPOSTWithHttpInfo(personMergeRequest, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); } /** - * Paginate through Opportunities in Affinity. Returns basic information but **not** field data on each Opportunity. To access field data on Opportunities, use the `/lists/{list_id}/list-entries` or the `/v2/lists/{list_id}/saved-views/{view_id}/list-entries` GET endpoint. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Get all Opportunities + * Retrieve paginated person merge tasks for the organization. Returns all merge tasks initiated by users in your organization, including their current status, the persons involved, and task details. You can filter tasks using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties: | Property | Type | Operators | Values | Examples | |----------|------|-----------|--------|----------| | `status` | `enum` | `=` | `in-progress`, `success`, `failed` | `status=failed` | Tasks are returned in reverse chronological order (most recent first). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get All Person Merge Tasks * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page - * @param [ids] Opportunity IDs + * @param [filter] Filter tasks using Affinity Filtering Language */ - public getV2OpportunitiesWithHttpInfo(cursor?: string, limit?: number, ids?: Array, _options?: ConfigurationOptions): Observable> { - let _config = this.configuration; - let allMiddleware: Middleware[] = []; - if (_options && _options.middleware){ - const middlewareMergeStrategy = _options.middlewareMergeStrategy || 'replace' // default to replace behavior - // call-time middleware provided - const calltimeMiddleware: Middleware[] = _options.middleware; - - switch(middlewareMergeStrategy){ - case 'append': - allMiddleware = this.configuration.middleware.concat(calltimeMiddleware); - break; - case 'prepend': - allMiddleware = calltimeMiddleware.concat(this.configuration.middleware) - break; - case 'replace': - allMiddleware = calltimeMiddleware - break; - default: - throw new Error(`unrecognized middleware merge strategy '${middlewareMergeStrategy}'`) - } - } - if (_options){ - _config = { - baseServer: _options.baseServer || this.configuration.baseServer, - httpApi: _options.httpApi || this.configuration.httpApi, - authMethods: _options.authMethods || this.configuration.authMethods, - middleware: allMiddleware || this.configuration.middleware - }; - } - - const requestContextPromise = this.requestFactory.getV2Opportunities(cursor, limit, ids, _config); + public v2TasksPersonMergesGETWithHttpInfo(cursor?: string, limit?: number, filter?: string, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); + + const requestContextPromise = this.requestFactory.v2TasksPersonMergesGET(cursor, limit, filter, _config); // build promise chain let middlewarePreObservable = from(requestContextPromise); - for (const middleware of allMiddleware) { + for (const middleware of _config.middleware) { middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); } - return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => this.configuration.httpApi.send(ctx))). + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). pipe(mergeMap((response: ResponseContext) => { let middlewarePostObservable = of(response); - for (const middleware of allMiddleware.reverse()) { + for (const middleware of _config.middleware.reverse()) { middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); } - return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.getV2OpportunitiesWithHttpInfo(rsp))); + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2TasksPersonMergesGETWithHttpInfo(rsp))); })); } /** - * Paginate through Opportunities in Affinity. Returns basic information but **not** field data on each Opportunity. To access field data on Opportunities, use the `/lists/{list_id}/list-entries` or the `/v2/lists/{list_id}/saved-views/{view_id}/list-entries` GET endpoint. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Get all Opportunities + * Retrieve paginated person merge tasks for the organization. Returns all merge tasks initiated by users in your organization, including their current status, the persons involved, and task details. You can filter tasks using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties: | Property | Type | Operators | Values | Examples | |----------|------|-----------|--------|----------| | `status` | `enum` | `=` | `in-progress`, `success`, `failed` | `status=failed` | Tasks are returned in reverse chronological order (most recent first). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get All Person Merge Tasks * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page - * @param [ids] Opportunity IDs + * @param [filter] Filter tasks using Affinity Filtering Language */ - public getV2Opportunities(cursor?: string, limit?: number, ids?: Array, _options?: ConfigurationOptions): Observable { - return this.getV2OpportunitiesWithHttpInfo(cursor, limit, ids, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + public v2TasksPersonMergesGET(cursor?: string, limit?: number, filter?: string, _options?: ConfigurationOptions): Observable { + return this.v2TasksPersonMergesGETWithHttpInfo(cursor, limit, filter, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); } /** - * Returns basic information but **not** field data on the requested Opportunity. To access field data on Opportunities, use the `/lists/{list_id}/list-entries` or the `/v2/lists/{list_id}/saved-views/{view_id}/list-entries` GET endpoint. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Get a single Opportunity - * @param id Opportunity ID - */ - public getV2OpportunitiesIdWithHttpInfo(id: number, _options?: ConfigurationOptions): Observable> { - let _config = this.configuration; - let allMiddleware: Middleware[] = []; - if (_options && _options.middleware){ - const middlewareMergeStrategy = _options.middlewareMergeStrategy || 'replace' // default to replace behavior - // call-time middleware provided - const calltimeMiddleware: Middleware[] = _options.middleware; - - switch(middlewareMergeStrategy){ - case 'append': - allMiddleware = this.configuration.middleware.concat(calltimeMiddleware); - break; - case 'prepend': - allMiddleware = calltimeMiddleware.concat(this.configuration.middleware) - break; - case 'replace': - allMiddleware = calltimeMiddleware - break; - default: - throw new Error(`unrecognized middleware merge strategy '${middlewareMergeStrategy}'`) - } - } - if (_options){ - _config = { - baseServer: _options.baseServer || this.configuration.baseServer, - httpApi: _options.httpApi || this.configuration.httpApi, - authMethods: _options.authMethods || this.configuration.authMethods, - middleware: allMiddleware || this.configuration.middleware - }; - } - - const requestContextPromise = this.requestFactory.getV2OpportunitiesId(id, _config); + * Retrieve the status and details of a specific task for person merges. Returns information about the person merges for a specific task including its overall status, number of merges in-progress, completed, and failed. Detailed information about individual merges for this task can be found by querying: `/v2/person-merges?filter=taskId={taskId}` See [Person Merges](#tag/personMerges/operation/v2_person-merges__GET) for more details. Task statuses: - `in-progress`: The merge task is currently being processed. - `success`: The merge task completed successfully. - `failed`: The merge task failed. Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get Person Merge Task + * @param taskId Person merge task ID + */ + public v2TasksPersonMergesTaskIdGETWithHttpInfo(taskId: string, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); + + const requestContextPromise = this.requestFactory.v2TasksPersonMergesTaskIdGET(taskId, _config); // build promise chain let middlewarePreObservable = from(requestContextPromise); - for (const middleware of allMiddleware) { + for (const middleware of _config.middleware) { middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); } - return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => this.configuration.httpApi.send(ctx))). + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). pipe(mergeMap((response: ResponseContext) => { let middlewarePostObservable = of(response); - for (const middleware of allMiddleware.reverse()) { + for (const middleware of _config.middleware.reverse()) { middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); } - return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.getV2OpportunitiesIdWithHttpInfo(rsp))); + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2TasksPersonMergesTaskIdGETWithHttpInfo(rsp))); })); } /** - * Returns basic information but **not** field data on the requested Opportunity. To access field data on Opportunities, use the `/lists/{list_id}/list-entries` or the `/v2/lists/{list_id}/saved-views/{view_id}/list-entries` GET endpoint. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Get a single Opportunity - * @param id Opportunity ID + * Retrieve the status and details of a specific task for person merges. Returns information about the person merges for a specific task including its overall status, number of merges in-progress, completed, and failed. Detailed information about individual merges for this task can be found by querying: `/v2/person-merges?filter=taskId={taskId}` See [Person Merges](#tag/personMerges/operation/v2_person-merges__GET) for more details. Task statuses: - `in-progress`: The merge task is currently being processed. - `success`: The merge task completed successfully. - `failed`: The merge task failed. Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get Person Merge Task + * @param taskId Person merge task ID */ - public getV2OpportunitiesId(id: number, _options?: ConfigurationOptions): Observable { - return this.getV2OpportunitiesIdWithHttpInfo(id, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + public v2TasksPersonMergesTaskIdGET(taskId: string, _options?: ConfigurationOptions): Observable { + return this.v2TasksPersonMergesTaskIdGETWithHttpInfo(taskId, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); } } @@ -1507,335 +1955,237 @@ export class ObservablePersonsApi { } /** - * Paginate through Persons in Affinity. Returns basic information and non-list-specific field data on each Person. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/persons/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Persons will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All People directory\" [permission](#section/Getting-Started/Permissions). - * Get all Persons + * Returns metadata on non-list-specific Person Fields. Use the returned Field IDs to request field data from the GET `/v2/persons` and GET `/v2/persons/{id}` endpoints. + * Get metadata on Person Fields * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page - * @param [ids] People IDs - * @param [fieldIds] Field IDs for which to return field data - * @param [fieldTypes] Field Types for which to return field data */ - public getV2PersonsWithHttpInfo(cursor?: string, limit?: number, ids?: Array, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: ConfigurationOptions): Observable> { - let _config = this.configuration; - let allMiddleware: Middleware[] = []; - if (_options && _options.middleware){ - const middlewareMergeStrategy = _options.middlewareMergeStrategy || 'replace' // default to replace behavior - // call-time middleware provided - const calltimeMiddleware: Middleware[] = _options.middleware; - - switch(middlewareMergeStrategy){ - case 'append': - allMiddleware = this.configuration.middleware.concat(calltimeMiddleware); - break; - case 'prepend': - allMiddleware = calltimeMiddleware.concat(this.configuration.middleware) - break; - case 'replace': - allMiddleware = calltimeMiddleware - break; - default: - throw new Error(`unrecognized middleware merge strategy '${middlewareMergeStrategy}'`) - } - } - if (_options){ - _config = { - baseServer: _options.baseServer || this.configuration.baseServer, - httpApi: _options.httpApi || this.configuration.httpApi, - authMethods: _options.authMethods || this.configuration.authMethods, - middleware: allMiddleware || this.configuration.middleware - }; - } - - const requestContextPromise = this.requestFactory.getV2Persons(cursor, limit, ids, fieldIds, fieldTypes, _config); + public v2PersonsFieldsGETWithHttpInfo(cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); + + const requestContextPromise = this.requestFactory.v2PersonsFieldsGET(cursor, limit, _config); // build promise chain let middlewarePreObservable = from(requestContextPromise); - for (const middleware of allMiddleware) { + for (const middleware of _config.middleware) { middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); } - return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => this.configuration.httpApi.send(ctx))). + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). pipe(mergeMap((response: ResponseContext) => { let middlewarePostObservable = of(response); - for (const middleware of allMiddleware.reverse()) { + for (const middleware of _config.middleware.reverse()) { middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); } - return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.getV2PersonsWithHttpInfo(rsp))); + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2PersonsFieldsGETWithHttpInfo(rsp))); })); } /** - * Paginate through Persons in Affinity. Returns basic information and non-list-specific field data on each Person. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/persons/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Persons will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All People directory\" [permission](#section/Getting-Started/Permissions). - * Get all Persons + * Returns metadata on non-list-specific Person Fields. Use the returned Field IDs to request field data from the GET `/v2/persons` and GET `/v2/persons/{id}` endpoints. + * Get metadata on Person Fields * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page - * @param [ids] People IDs - * @param [fieldIds] Field IDs for which to return field data - * @param [fieldTypes] Field Types for which to return field data */ - public getV2Persons(cursor?: string, limit?: number, ids?: Array, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: ConfigurationOptions): Observable { - return this.getV2PersonsWithHttpInfo(cursor, limit, ids, fieldIds, fieldTypes, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + public v2PersonsFieldsGET(cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable { + return this.v2PersonsFieldsGETWithHttpInfo(cursor, limit, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); } /** - * Returns metadata on non-list-specific Person Fields. Use the returned Field IDs to request field data from the GET `/v2/persons` and GET `/v2/persons/{id}` endpoints. - * Get metadata on Person Fields + * Paginate through Persons in Affinity. Returns basic information and non-list-specific field data on each Person. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/persons/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Persons will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All People directory\" [permission](#section/Getting-Started/Permissions). + * Get all Persons * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page + * @param [ids] People IDs + * @param [fieldIds] Field IDs for which to return field data + * @param [fieldTypes] Field Types for which to return field data */ - public getV2PersonsFieldsWithHttpInfo(cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable> { - let _config = this.configuration; - let allMiddleware: Middleware[] = []; - if (_options && _options.middleware){ - const middlewareMergeStrategy = _options.middlewareMergeStrategy || 'replace' // default to replace behavior - // call-time middleware provided - const calltimeMiddleware: Middleware[] = _options.middleware; - - switch(middlewareMergeStrategy){ - case 'append': - allMiddleware = this.configuration.middleware.concat(calltimeMiddleware); - break; - case 'prepend': - allMiddleware = calltimeMiddleware.concat(this.configuration.middleware) - break; - case 'replace': - allMiddleware = calltimeMiddleware - break; - default: - throw new Error(`unrecognized middleware merge strategy '${middlewareMergeStrategy}'`) - } - } - if (_options){ - _config = { - baseServer: _options.baseServer || this.configuration.baseServer, - httpApi: _options.httpApi || this.configuration.httpApi, - authMethods: _options.authMethods || this.configuration.authMethods, - middleware: allMiddleware || this.configuration.middleware - }; - } - - const requestContextPromise = this.requestFactory.getV2PersonsFields(cursor, limit, _config); + public v2PersonsGETWithHttpInfo(cursor?: string, limit?: number, ids?: Array, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); + + const requestContextPromise = this.requestFactory.v2PersonsGET(cursor, limit, ids, fieldIds, fieldTypes, _config); // build promise chain let middlewarePreObservable = from(requestContextPromise); - for (const middleware of allMiddleware) { + for (const middleware of _config.middleware) { middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); } - return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => this.configuration.httpApi.send(ctx))). + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). pipe(mergeMap((response: ResponseContext) => { let middlewarePostObservable = of(response); - for (const middleware of allMiddleware.reverse()) { + for (const middleware of _config.middleware.reverse()) { middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); } - return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.getV2PersonsFieldsWithHttpInfo(rsp))); + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2PersonsGETWithHttpInfo(rsp))); })); } /** - * Returns metadata on non-list-specific Person Fields. Use the returned Field IDs to request field data from the GET `/v2/persons` and GET `/v2/persons/{id}` endpoints. - * Get metadata on Person Fields + * Paginate through Persons in Affinity. Returns basic information and non-list-specific field data on each Person. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/persons/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Persons will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All People directory\" [permission](#section/Getting-Started/Permissions). + * Get all Persons * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page + * @param [ids] People IDs + * @param [fieldIds] Field IDs for which to return field data + * @param [fieldTypes] Field Types for which to return field data */ - public getV2PersonsFields(cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable { - return this.getV2PersonsFieldsWithHttpInfo(cursor, limit, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + public v2PersonsGET(cursor?: string, limit?: number, ids?: Array, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: ConfigurationOptions): Observable { + return this.v2PersonsGETWithHttpInfo(cursor, limit, ids, fieldIds, fieldTypes, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); } /** * Returns basic information and non-list-specific field data on the requested Person. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/persons/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Persons will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All People directory\" [permission](#section/Getting-Started/Permissions). * Get a single Person - * @param id Person ID + * @param personId Person ID * @param [fieldIds] Field IDs for which to return field data * @param [fieldTypes] Field Types for which to return field data */ - public getV2PersonsIdWithHttpInfo(id: number, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: ConfigurationOptions): Observable> { - let _config = this.configuration; - let allMiddleware: Middleware[] = []; - if (_options && _options.middleware){ - const middlewareMergeStrategy = _options.middlewareMergeStrategy || 'replace' // default to replace behavior - // call-time middleware provided - const calltimeMiddleware: Middleware[] = _options.middleware; - - switch(middlewareMergeStrategy){ - case 'append': - allMiddleware = this.configuration.middleware.concat(calltimeMiddleware); - break; - case 'prepend': - allMiddleware = calltimeMiddleware.concat(this.configuration.middleware) - break; - case 'replace': - allMiddleware = calltimeMiddleware - break; - default: - throw new Error(`unrecognized middleware merge strategy '${middlewareMergeStrategy}'`) - } - } - if (_options){ - _config = { - baseServer: _options.baseServer || this.configuration.baseServer, - httpApi: _options.httpApi || this.configuration.httpApi, - authMethods: _options.authMethods || this.configuration.authMethods, - middleware: allMiddleware || this.configuration.middleware - }; - } - - const requestContextPromise = this.requestFactory.getV2PersonsId(id, fieldIds, fieldTypes, _config); + public v2PersonsPersonIdGETWithHttpInfo(personId: number, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); + + const requestContextPromise = this.requestFactory.v2PersonsPersonIdGET(personId, fieldIds, fieldTypes, _config); // build promise chain let middlewarePreObservable = from(requestContextPromise); - for (const middleware of allMiddleware) { + for (const middleware of _config.middleware) { middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); } - return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => this.configuration.httpApi.send(ctx))). + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). pipe(mergeMap((response: ResponseContext) => { let middlewarePostObservable = of(response); - for (const middleware of allMiddleware.reverse()) { + for (const middleware of _config.middleware.reverse()) { middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); } - return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.getV2PersonsIdWithHttpInfo(rsp))); + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2PersonsPersonIdGETWithHttpInfo(rsp))); })); } /** * Returns basic information and non-list-specific field data on the requested Person. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/persons/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Persons will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All People directory\" [permission](#section/Getting-Started/Permissions). * Get a single Person - * @param id Person ID + * @param personId Person ID * @param [fieldIds] Field IDs for which to return field data * @param [fieldTypes] Field Types for which to return field data */ - public getV2PersonsId(id: number, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: ConfigurationOptions): Observable { - return this.getV2PersonsIdWithHttpInfo(id, fieldIds, fieldTypes, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + public v2PersonsPersonIdGET(personId: number, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: ConfigurationOptions): Observable { + return this.v2PersonsPersonIdGETWithHttpInfo(personId, fieldIds, fieldTypes, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); } /** * Paginate through the List Entries (AKA rows) for the given Person across all Lists. Each List Entry includes field data for the Person, including list-specific field data. Each List Entry also includes metadata about its creation, i.e., when it was added to the List and by whom. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). * Get a Person\'s List Entries - * @param id Persons ID + * @param personId Persons ID * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page */ - public getV2PersonsIdListEntriesWithHttpInfo(id: number, cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable> { - let _config = this.configuration; - let allMiddleware: Middleware[] = []; - if (_options && _options.middleware){ - const middlewareMergeStrategy = _options.middlewareMergeStrategy || 'replace' // default to replace behavior - // call-time middleware provided - const calltimeMiddleware: Middleware[] = _options.middleware; - - switch(middlewareMergeStrategy){ - case 'append': - allMiddleware = this.configuration.middleware.concat(calltimeMiddleware); - break; - case 'prepend': - allMiddleware = calltimeMiddleware.concat(this.configuration.middleware) - break; - case 'replace': - allMiddleware = calltimeMiddleware - break; - default: - throw new Error(`unrecognized middleware merge strategy '${middlewareMergeStrategy}'`) - } - } - if (_options){ - _config = { - baseServer: _options.baseServer || this.configuration.baseServer, - httpApi: _options.httpApi || this.configuration.httpApi, - authMethods: _options.authMethods || this.configuration.authMethods, - middleware: allMiddleware || this.configuration.middleware - }; - } - - const requestContextPromise = this.requestFactory.getV2PersonsIdListEntries(id, cursor, limit, _config); + public v2PersonsPersonIdListEntriesGETWithHttpInfo(personId: number, cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); + + const requestContextPromise = this.requestFactory.v2PersonsPersonIdListEntriesGET(personId, cursor, limit, _config); // build promise chain let middlewarePreObservable = from(requestContextPromise); - for (const middleware of allMiddleware) { + for (const middleware of _config.middleware) { middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); } - return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => this.configuration.httpApi.send(ctx))). + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). pipe(mergeMap((response: ResponseContext) => { let middlewarePostObservable = of(response); - for (const middleware of allMiddleware.reverse()) { + for (const middleware of _config.middleware.reverse()) { middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); } - return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.getV2PersonsIdListEntriesWithHttpInfo(rsp))); + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2PersonsPersonIdListEntriesGETWithHttpInfo(rsp))); })); } /** * Paginate through the List Entries (AKA rows) for the given Person across all Lists. Each List Entry includes field data for the Person, including list-specific field data. Each List Entry also includes metadata about its creation, i.e., when it was added to the List and by whom. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). * Get a Person\'s List Entries - * @param id Persons ID + * @param personId Persons ID * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page */ - public getV2PersonsIdListEntries(id: number, cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable { - return this.getV2PersonsIdListEntriesWithHttpInfo(id, cursor, limit, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + public v2PersonsPersonIdListEntriesGET(personId: number, cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable { + return this.v2PersonsPersonIdListEntriesGETWithHttpInfo(personId, cursor, limit, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); } /** - * Returns metadata for all the Lists on which the given Person appears. + * Paginate through all Lists where the given Person appears as an entry and that you have access to view. Returns basic List information for each List that contains this Person. * Get a Person\'s Lists - * @param id Persons ID + * @param personId Persons ID * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page */ - public getV2PersonsIdListsWithHttpInfo(id: number, cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable> { - let _config = this.configuration; - let allMiddleware: Middleware[] = []; - if (_options && _options.middleware){ - const middlewareMergeStrategy = _options.middlewareMergeStrategy || 'replace' // default to replace behavior - // call-time middleware provided - const calltimeMiddleware: Middleware[] = _options.middleware; - - switch(middlewareMergeStrategy){ - case 'append': - allMiddleware = this.configuration.middleware.concat(calltimeMiddleware); - break; - case 'prepend': - allMiddleware = calltimeMiddleware.concat(this.configuration.middleware) - break; - case 'replace': - allMiddleware = calltimeMiddleware - break; - default: - throw new Error(`unrecognized middleware merge strategy '${middlewareMergeStrategy}'`) - } - } - if (_options){ - _config = { - baseServer: _options.baseServer || this.configuration.baseServer, - httpApi: _options.httpApi || this.configuration.httpApi, - authMethods: _options.authMethods || this.configuration.authMethods, - middleware: allMiddleware || this.configuration.middleware - }; - } - - const requestContextPromise = this.requestFactory.getV2PersonsIdLists(id, cursor, limit, _config); + public v2PersonsPersonIdListsGETWithHttpInfo(personId: number, cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); + + const requestContextPromise = this.requestFactory.v2PersonsPersonIdListsGET(personId, cursor, limit, _config); // build promise chain let middlewarePreObservable = from(requestContextPromise); - for (const middleware of allMiddleware) { + for (const middleware of _config.middleware) { middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); } - return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => this.configuration.httpApi.send(ctx))). + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). pipe(mergeMap((response: ResponseContext) => { let middlewarePostObservable = of(response); - for (const middleware of allMiddleware.reverse()) { + for (const middleware of _config.middleware.reverse()) { middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); } - return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.getV2PersonsIdListsWithHttpInfo(rsp))); + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2PersonsPersonIdListsGETWithHttpInfo(rsp))); })); } /** - * Returns metadata for all the Lists on which the given Person appears. + * Paginate through all Lists where the given Person appears as an entry and that you have access to view. Returns basic List information for each List that contains this Person. * Get a Person\'s Lists - * @param id Persons ID + * @param personId Persons ID + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + */ + public v2PersonsPersonIdListsGET(personId: number, cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable { + return this.v2PersonsPersonIdListsGETWithHttpInfo(personId, cursor, limit, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + } + + /** + * | ⚠️ This endpoint is currently in BETA | |--| Returns notes for a given person id which includes directly attached notes, notes on meetings this person attended, and notes where this person is mentioned. You can filter notes using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|---------------------------------| | `creator.id` | Filter notes by the creator of the note | `int32` | `=` | `creator.id=1` | | `createdAt` | Filter notes by when it was created | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-02-04T10:48:24Z` | | `updatedAt` | Filter notes by when it was updated | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-02-03T10:48:24Z`| + * Get Notes for a Person + * @param personId Persons ID + * @param [filter] Filter options + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + * @param [totalCount] Include total count of the collection in the pagination response + */ + public v2PersonsPersonIdNotesGETWithHttpInfo(personId: number, filter?: string, cursor?: string, limit?: number, totalCount?: boolean, _options?: ConfigurationOptions): Observable> { + const _config = mergeConfiguration(this.configuration, _options); + + const requestContextPromise = this.requestFactory.v2PersonsPersonIdNotesGET(personId, filter, cursor, limit, totalCount, _config); + // build promise chain + let middlewarePreObservable = from(requestContextPromise); + for (const middleware of _config.middleware) { + middlewarePreObservable = middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => middleware.pre(ctx))); + } + + return middlewarePreObservable.pipe(mergeMap((ctx: RequestContext) => _config.httpApi.send(ctx))). + pipe(mergeMap((response: ResponseContext) => { + let middlewarePostObservable = of(response); + for (const middleware of _config.middleware.reverse()) { + middlewarePostObservable = middlewarePostObservable.pipe(mergeMap((rsp: ResponseContext) => middleware.post(rsp))); + } + return middlewarePostObservable.pipe(map((rsp: ResponseContext) => this.responseProcessor.v2PersonsPersonIdNotesGETWithHttpInfo(rsp))); + })); + } + + /** + * | ⚠️ This endpoint is currently in BETA | |--| Returns notes for a given person id which includes directly attached notes, notes on meetings this person attended, and notes where this person is mentioned. You can filter notes using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|---------------------------------| | `creator.id` | Filter notes by the creator of the note | `int32` | `=` | `creator.id=1` | | `createdAt` | Filter notes by when it was created | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-02-04T10:48:24Z` | | `updatedAt` | Filter notes by when it was updated | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-02-03T10:48:24Z`| + * Get Notes for a Person + * @param personId Persons ID + * @param [filter] Filter options * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page + * @param [totalCount] Include total count of the collection in the pagination response */ - public getV2PersonsIdLists(id: number, cursor?: string, limit?: number, _options?: ConfigurationOptions): Observable { - return this.getV2PersonsIdListsWithHttpInfo(id, cursor, limit, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); + public v2PersonsPersonIdNotesGET(personId: number, filter?: string, cursor?: string, limit?: number, totalCount?: boolean, _options?: ConfigurationOptions): Observable { + return this.v2PersonsPersonIdNotesGETWithHttpInfo(personId, filter, cursor, limit, totalCount, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); } } diff --git a/src/v2/generated/types/PromiseAPI.ts b/src/v2/generated/types/PromiseAPI.ts index 5368822..21daddd 100644 --- a/src/v2/generated/types/PromiseAPI.ts +++ b/src/v2/generated/types/PromiseAPI.ts @@ -1,8 +1,9 @@ import { ResponseContext, RequestContext, HttpFile, HttpInfo } from '../http/http.ts'; -import { Configuration, ConfigurationOptions, PromiseConfigurationOptions } from '../configuration.ts' +import { Configuration, PromiseConfigurationOptions, wrapOptions } from '../configuration.ts' import { PromiseMiddleware, Middleware, PromiseMiddlewareWrapper } from '../middleware.ts'; import { Attendee } from '../models/Attendee.ts'; +import { AttendeesPreview } from '../models/AttendeesPreview.ts'; import { AuthenticationError } from '../models/AuthenticationError.ts'; import { AuthorizationError } from '../models/AuthorizationError.ts'; import { AuthorizationErrors } from '../models/AuthorizationErrors.ts'; @@ -12,7 +13,15 @@ import { CompaniesValue } from '../models/CompaniesValue.ts'; import { CompaniesValueUpdate } from '../models/CompaniesValueUpdate.ts'; import { Company } from '../models/Company.ts'; import { CompanyData } from '../models/CompanyData.ts'; +import { CompanyDataPaged } from '../models/CompanyDataPaged.ts'; import { CompanyListEntry } from '../models/CompanyListEntry.ts'; +import { CompanyMergeRequest } from '../models/CompanyMergeRequest.ts'; +import { CompanyMergeResponse } from '../models/CompanyMergeResponse.ts'; +import { CompanyMergeState } from '../models/CompanyMergeState.ts'; +import { CompanyMergeStatePaged } from '../models/CompanyMergeStatePaged.ts'; +import { CompanyMergeTask } from '../models/CompanyMergeTask.ts'; +import { CompanyMergeTaskPaged } from '../models/CompanyMergeTaskPaged.ts'; +import { CompanyMergeTaskResultsSummary } from '../models/CompanyMergeTaskResultsSummary.ts'; import { CompanyPaged } from '../models/CompanyPaged.ts'; import { CompanyReference } from '../models/CompanyReference.ts'; import { CompanyValue } from '../models/CompanyValue.ts'; @@ -39,10 +48,16 @@ import { FloatsValue } from '../models/FloatsValue.ts'; import { FormulaNumber } from '../models/FormulaNumber.ts'; import { FormulaValue } from '../models/FormulaValue.ts'; import { Grant } from '../models/Grant.ts'; -import { InlineObject } from '../models/InlineObject.ts'; -import { InlineObjectErrorsInner } from '../models/InlineObjectErrorsInner.ts'; import { Interaction } from '../models/Interaction.ts'; import { InteractionValue } from '../models/InteractionValue.ts'; +import { InteractionsCall } from '../models/InteractionsCall.ts'; +import { InteractionsCallPaged } from '../models/InteractionsCallPaged.ts'; +import { InteractionsChatMessage } from '../models/InteractionsChatMessage.ts'; +import { InteractionsChatMessagePaged } from '../models/InteractionsChatMessagePaged.ts'; +import { InteractionsEmail } from '../models/InteractionsEmail.ts'; +import { InteractionsEmailPaged } from '../models/InteractionsEmailPaged.ts'; +import { InteractionsMeeting } from '../models/InteractionsMeeting.ts'; +import { InteractionsMeetingPaged } from '../models/InteractionsMeetingPaged.ts'; import { List } from '../models/List.ts'; import { ListEntry } from '../models/ListEntry.ts'; import { ListEntryBatchOperationResponse } from '../models/ListEntryBatchOperationResponse.ts'; @@ -65,14 +80,47 @@ import { NotAcceptableError } from '../models/NotAcceptableError.ts'; import { NotFoundError } from '../models/NotFoundError.ts'; import { NotFoundErrors } from '../models/NotFoundErrors.ts'; import { NotImplementedError } from '../models/NotImplementedError.ts'; +import { NotesAiNotetakerReplyNote } from '../models/NotesAiNotetakerReplyNote.ts'; +import { NotesAiNotetakerRootNote } from '../models/NotesAiNotetakerRootNote.ts'; +import { NotesBaseNote } from '../models/NotesBaseNote.ts'; +import { NotesBaseReply } from '../models/NotesBaseReply.ts'; +import { NotesBaseReplyParent } from '../models/NotesBaseReplyParent.ts'; +import { NotesBaseRootNote } from '../models/NotesBaseRootNote.ts'; +import { NotesCallInteraction } from '../models/NotesCallInteraction.ts'; +import { NotesChatMessageInteraction } from '../models/NotesChatMessageInteraction.ts'; +import { NotesCompaniesPreview } from '../models/NotesCompaniesPreview.ts'; +import { NotesContent } from '../models/NotesContent.ts'; +import { NotesEmailInteraction } from '../models/NotesEmailInteraction.ts'; +import { NotesEntitiesNote } from '../models/NotesEntitiesNote.ts'; +import { NotesInteraction } from '../models/NotesInteraction.ts'; +import { NotesInteractionNote } from '../models/NotesInteractionNote.ts'; +import { NotesMeetingInteraction } from '../models/NotesMeetingInteraction.ts'; +import { NotesNote } from '../models/NotesNote.ts'; +import { NotesNotesPaged } from '../models/NotesNotesPaged.ts'; +import { NotesOpportunitiesPreview } from '../models/NotesOpportunitiesPreview.ts'; +import { NotesPermissionSettings } from '../models/NotesPermissionSettings.ts'; +import { NotesPersonMention } from '../models/NotesPersonMention.ts'; +import { NotesPersonsPreview } from '../models/NotesPersonsPreview.ts'; +import { NotesRepliesPaged } from '../models/NotesRepliesPaged.ts'; +import { NotesReply } from '../models/NotesReply.ts'; +import { NotesUserReplyNote } from '../models/NotesUserReplyNote.ts'; import { Opportunity } from '../models/Opportunity.ts'; import { OpportunityListEntry } from '../models/OpportunityListEntry.ts'; import { OpportunityPaged } from '../models/OpportunityPaged.ts'; import { OpportunityWithFields } from '../models/OpportunityWithFields.ts'; import { Pagination } from '../models/Pagination.ts'; +import { PaginationWithTotalCount } from '../models/PaginationWithTotalCount.ts'; import { Person } from '../models/Person.ts'; import { PersonData } from '../models/PersonData.ts'; +import { PersonDataPaged } from '../models/PersonDataPaged.ts'; +import { PersonDataPreview } from '../models/PersonDataPreview.ts'; import { PersonListEntry } from '../models/PersonListEntry.ts'; +import { PersonMergeRequest } from '../models/PersonMergeRequest.ts'; +import { PersonMergeResponse } from '../models/PersonMergeResponse.ts'; +import { PersonMergeState } from '../models/PersonMergeState.ts'; +import { PersonMergeStatePaged } from '../models/PersonMergeStatePaged.ts'; +import { PersonMergeTask } from '../models/PersonMergeTask.ts'; +import { PersonMergeTaskPaged } from '../models/PersonMergeTaskPaged.ts'; import { PersonPaged } from '../models/PersonPaged.ts'; import { PersonReference } from '../models/PersonReference.ts'; import { PersonValue } from '../models/PersonValue.ts'; @@ -85,6 +133,8 @@ import { RankedDropdownReference } from '../models/RankedDropdownReference.ts'; import { RankedDropdownValue } from '../models/RankedDropdownValue.ts'; import { RankedDropdownValueUpdate } from '../models/RankedDropdownValueUpdate.ts'; import { RateLimitError } from '../models/RateLimitError.ts'; +import { Responses400 } from '../models/Responses400.ts'; +import { Responses400ErrorsInner } from '../models/Responses400ErrorsInner.ts'; import { SavedView } from '../models/SavedView.ts'; import { SavedViewPaged } from '../models/SavedViewPaged.ts'; import { ServerError } from '../models/ServerError.ts'; @@ -111,44 +161,22 @@ export class PromiseAuthApi { } /** - * Returns metadata about the current user. + * Returns information about the authenticated user, their current organization, and API key permissions. Use this endpoint to verify your authentication and understand your available API access levels. * Get current user */ - public getV2AuthWhoamiWithHttpInfo(_options?: PromiseConfigurationOptions): Promise> { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } - const result = this.api.getV2AuthWhoamiWithHttpInfo(observableOptions); + public v2AuthWhoamiGETWithHttpInfo(_options?: PromiseConfigurationOptions): Promise> { + const observableOptions = wrapOptions(_options); + const result = this.api.v2AuthWhoamiGETWithHttpInfo(observableOptions); return result.toPromise(); } /** - * Returns metadata about the current user. + * Returns information about the authenticated user, their current organization, and API key permissions. Use this endpoint to verify your authentication and understand your available API access levels. * Get current user */ - public getV2AuthWhoami(_options?: PromiseConfigurationOptions): Promise { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } - const result = this.api.getV2AuthWhoami(observableOptions); + public v2AuthWhoamiGET(_options?: PromiseConfigurationOptions): Promise { + const observableOptions = wrapOptions(_options); + const result = this.api.v2AuthWhoamiGET(observableOptions); return result.toPromise(); } @@ -157,259 +185,269 @@ export class PromiseAuthApi { -import { ObservableCompaniesApi } from './ObservableAPI.ts'; +import { ObservableCallsApi } from './ObservableAPI.ts'; -import { CompaniesApiRequestFactory, CompaniesApiResponseProcessor} from "../apis/CompaniesApi.ts"; -export class PromiseCompaniesApi { - private api: ObservableCompaniesApi +import { CallsApiRequestFactory, CallsApiResponseProcessor} from "../apis/CallsApi.ts"; +export class PromiseCallsApi { + private api: ObservableCallsApi public constructor( configuration: Configuration, - requestFactory?: CompaniesApiRequestFactory, - responseProcessor?: CompaniesApiResponseProcessor + requestFactory?: CallsApiRequestFactory, + responseProcessor?: CallsApiResponseProcessor ) { - this.api = new ObservableCompaniesApi(configuration, requestFactory, responseProcessor); + this.api = new ObservableCallsApi(configuration, requestFactory, responseProcessor); } /** - * Paginate through Companies in Affinity. Returns basic information and non-list-specific field data on each Company. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/companies/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Companies will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All Organizations directory\" [permission](#section/Getting-Started/Permissions). - * Get all Companies + * Paginate through all calls in Affinity. Returns basic information about the call interaction and its participants. Will only return calls that the current authenticated user has permission to see. You can filter calls using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|----------------------------------| | `id` | Unique identifier for Calls | `int64` | `=` | `id=1` | | `startTime` | Start time of when the Call was held | `datetime` | `>`, `<`, `>=`, `<=` | `sentAt>2025-01-01T01:00:00Z` | | `createdAt` | When the Call was created in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-01-01T01:00:00Z` | | `updatedAt` | When the Call was updated in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-01-01T01:00:00Z`| + * Get metadata on all Calls * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page - * @param [ids] Company IDs - * @param [fieldIds] Field IDs for which to return field data - * @param [fieldTypes] Field Types for which to return field data + * @param [filter] Filter options */ - public getV2CompaniesWithHttpInfo(cursor?: string, limit?: number, ids?: Array, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: PromiseConfigurationOptions): Promise> { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } - const result = this.api.getV2CompaniesWithHttpInfo(cursor, limit, ids, fieldIds, fieldTypes, observableOptions); + public v2CallsGETWithHttpInfo(cursor?: string, limit?: number, filter?: string, _options?: PromiseConfigurationOptions): Promise> { + const observableOptions = wrapOptions(_options); + const result = this.api.v2CallsGETWithHttpInfo(cursor, limit, filter, observableOptions); return result.toPromise(); } /** - * Paginate through Companies in Affinity. Returns basic information and non-list-specific field data on each Company. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/companies/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Companies will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All Organizations directory\" [permission](#section/Getting-Started/Permissions). - * Get all Companies + * Paginate through all calls in Affinity. Returns basic information about the call interaction and its participants. Will only return calls that the current authenticated user has permission to see. You can filter calls using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|----------------------------------| | `id` | Unique identifier for Calls | `int64` | `=` | `id=1` | | `startTime` | Start time of when the Call was held | `datetime` | `>`, `<`, `>=`, `<=` | `sentAt>2025-01-01T01:00:00Z` | | `createdAt` | When the Call was created in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-01-01T01:00:00Z` | | `updatedAt` | When the Call was updated in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-01-01T01:00:00Z`| + * Get metadata on all Calls * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page - * @param [ids] Company IDs - * @param [fieldIds] Field IDs for which to return field data - * @param [fieldTypes] Field Types for which to return field data + * @param [filter] Filter options */ - public getV2Companies(cursor?: string, limit?: number, ids?: Array, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: PromiseConfigurationOptions): Promise { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } - const result = this.api.getV2Companies(cursor, limit, ids, fieldIds, fieldTypes, observableOptions); + public v2CallsGET(cursor?: string, limit?: number, filter?: string, _options?: PromiseConfigurationOptions): Promise { + const observableOptions = wrapOptions(_options); + const result = this.api.v2CallsGET(cursor, limit, filter, observableOptions); return result.toPromise(); } + +} + + + +import { ObservableChatMessagesApi } from './ObservableAPI.ts'; + +import { ChatMessagesApiRequestFactory, ChatMessagesApiResponseProcessor} from "../apis/ChatMessagesApi.ts"; +export class PromiseChatMessagesApi { + private api: ObservableChatMessagesApi + + public constructor( + configuration: Configuration, + requestFactory?: ChatMessagesApiRequestFactory, + responseProcessor?: ChatMessagesApiResponseProcessor + ) { + this.api = new ObservableChatMessagesApi(configuration, requestFactory, responseProcessor); + } + /** - * Returns metadata on non-list-specific Company Fields. Use the returned Field IDs to request field data from the GET `/v2/companies` and GET `/v2/companies/{id}` endpoints. - * Get metadata on Company Fields + * Paginate through all chat messages in Affinity. Returns basic information about the chat message interaction and its participants. Will only return chat messages that the current authenticated user has permission to see. You can filter chat messages using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|----------------------------------| | `id` | Unique identifier for Chat Messages | `int64` | `=` | `id=1` | | `sentAt` | When the Chat Message was sent at | `datetime` | `>`, `<`, `>=`, `<=` | `sentAt>2025-01-01T01:00:00Z` | | `createdAt` | When the Chat Message was created in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-01-01T01:00:00Z` | | `updatedAt` | When the Chat Message was updated in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-01-01T01:00:00Z`| + * Get metadata on all Chat Messages * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page + * @param [filter] Filter options */ - public getV2CompaniesFieldsWithHttpInfo(cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise> { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } - const result = this.api.getV2CompaniesFieldsWithHttpInfo(cursor, limit, observableOptions); + public v2ChatMessagesGETWithHttpInfo(cursor?: string, limit?: number, filter?: string, _options?: PromiseConfigurationOptions): Promise> { + const observableOptions = wrapOptions(_options); + const result = this.api.v2ChatMessagesGETWithHttpInfo(cursor, limit, filter, observableOptions); return result.toPromise(); } /** - * Returns metadata on non-list-specific Company Fields. Use the returned Field IDs to request field data from the GET `/v2/companies` and GET `/v2/companies/{id}` endpoints. - * Get metadata on Company Fields + * Paginate through all chat messages in Affinity. Returns basic information about the chat message interaction and its participants. Will only return chat messages that the current authenticated user has permission to see. You can filter chat messages using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|----------------------------------| | `id` | Unique identifier for Chat Messages | `int64` | `=` | `id=1` | | `sentAt` | When the Chat Message was sent at | `datetime` | `>`, `<`, `>=`, `<=` | `sentAt>2025-01-01T01:00:00Z` | | `createdAt` | When the Chat Message was created in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-01-01T01:00:00Z` | | `updatedAt` | When the Chat Message was updated in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-01-01T01:00:00Z`| + * Get metadata on all Chat Messages * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page + * @param [filter] Filter options */ - public getV2CompaniesFields(cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } - const result = this.api.getV2CompaniesFields(cursor, limit, observableOptions); + public v2ChatMessagesGET(cursor?: string, limit?: number, filter?: string, _options?: PromiseConfigurationOptions): Promise { + const observableOptions = wrapOptions(_options); + const result = this.api.v2ChatMessagesGET(cursor, limit, filter, observableOptions); return result.toPromise(); } + +} + + + +import { ObservableCompaniesApi } from './ObservableAPI.ts'; + +import { CompaniesApiRequestFactory, CompaniesApiResponseProcessor} from "../apis/CompaniesApi.ts"; +export class PromiseCompaniesApi { + private api: ObservableCompaniesApi + + public constructor( + configuration: Configuration, + requestFactory?: CompaniesApiRequestFactory, + responseProcessor?: CompaniesApiResponseProcessor + ) { + this.api = new ObservableCompaniesApi(configuration, requestFactory, responseProcessor); + } + /** * Returns basic information and non-list-specific field data on the requested Company. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/companies/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Companies will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All Organizations directory\" [permission](#section/Getting-Started/Permissions). * Get a single Company - * @param id Company ID + * @param companyId Company ID * @param [fieldIds] Field IDs for which to return field data * @param [fieldTypes] Field Types for which to return field data */ - public getV2CompaniesIdWithHttpInfo(id: number, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: PromiseConfigurationOptions): Promise> { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } - const result = this.api.getV2CompaniesIdWithHttpInfo(id, fieldIds, fieldTypes, observableOptions); + public v2CompaniesCompanyIdGETWithHttpInfo(companyId: number, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: PromiseConfigurationOptions): Promise> { + const observableOptions = wrapOptions(_options); + const result = this.api.v2CompaniesCompanyIdGETWithHttpInfo(companyId, fieldIds, fieldTypes, observableOptions); return result.toPromise(); } /** * Returns basic information and non-list-specific field data on the requested Company. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/companies/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Companies will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All Organizations directory\" [permission](#section/Getting-Started/Permissions). * Get a single Company - * @param id Company ID + * @param companyId Company ID * @param [fieldIds] Field IDs for which to return field data * @param [fieldTypes] Field Types for which to return field data */ - public getV2CompaniesId(id: number, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: PromiseConfigurationOptions): Promise { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } - const result = this.api.getV2CompaniesId(id, fieldIds, fieldTypes, observableOptions); + public v2CompaniesCompanyIdGET(companyId: number, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: PromiseConfigurationOptions): Promise { + const observableOptions = wrapOptions(_options); + const result = this.api.v2CompaniesCompanyIdGET(companyId, fieldIds, fieldTypes, observableOptions); return result.toPromise(); } /** * Paginate through the List Entries (AKA rows) for the given Company across all Lists. Each List Entry includes field data for the Company, including list-specific field data. Each List Entry also includes metadata about its creation, i.e., when it was added to the List and by whom. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). * Get a Company\'s List Entries - * @param id Company ID + * @param companyId Company ID * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page */ - public getV2CompaniesIdListEntriesWithHttpInfo(id: number, cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise> { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } - const result = this.api.getV2CompaniesIdListEntriesWithHttpInfo(id, cursor, limit, observableOptions); + public v2CompaniesCompanyIdListEntriesGETWithHttpInfo(companyId: number, cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise> { + const observableOptions = wrapOptions(_options); + const result = this.api.v2CompaniesCompanyIdListEntriesGETWithHttpInfo(companyId, cursor, limit, observableOptions); return result.toPromise(); } /** * Paginate through the List Entries (AKA rows) for the given Company across all Lists. Each List Entry includes field data for the Company, including list-specific field data. Each List Entry also includes metadata about its creation, i.e., when it was added to the List and by whom. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). * Get a Company\'s List Entries - * @param id Company ID + * @param companyId Company ID * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page */ - public getV2CompaniesIdListEntries(id: number, cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } - const result = this.api.getV2CompaniesIdListEntries(id, cursor, limit, observableOptions); + public v2CompaniesCompanyIdListEntriesGET(companyId: number, cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise { + const observableOptions = wrapOptions(_options); + const result = this.api.v2CompaniesCompanyIdListEntriesGET(companyId, cursor, limit, observableOptions); return result.toPromise(); } /** - * Returns metadata for all the Lists on which the given Company appears. + * Paginate through all Lists where the given Company appears as an entry and that you have access to view. Returns basic List information for each List that contains this Company. * Get a Company\'s Lists - * @param id Company ID + * @param companyId Company ID * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page */ - public getV2CompaniesIdListsWithHttpInfo(id: number, cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise> { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } - const result = this.api.getV2CompaniesIdListsWithHttpInfo(id, cursor, limit, observableOptions); + public v2CompaniesCompanyIdListsGETWithHttpInfo(companyId: number, cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise> { + const observableOptions = wrapOptions(_options); + const result = this.api.v2CompaniesCompanyIdListsGETWithHttpInfo(companyId, cursor, limit, observableOptions); return result.toPromise(); } /** - * Returns metadata for all the Lists on which the given Company appears. + * Paginate through all Lists where the given Company appears as an entry and that you have access to view. Returns basic List information for each List that contains this Company. * Get a Company\'s Lists - * @param id Company ID + * @param companyId Company ID * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page */ - public getV2CompaniesIdLists(id: number, cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } - const result = this.api.getV2CompaniesIdLists(id, cursor, limit, observableOptions); + public v2CompaniesCompanyIdListsGET(companyId: number, cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise { + const observableOptions = wrapOptions(_options); + const result = this.api.v2CompaniesCompanyIdListsGET(companyId, cursor, limit, observableOptions); + return result.toPromise(); + } + + /** + * | ⚠️ This endpoint is currently in BETA | |--| Returns relevant notes for a given company which includes directly attached notes and notes attached to persons on this company. You can filter notes using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|---------------------------------| | `creator.id` | Filter notes by the creator of the note | `int32` | `=` | `creator.id=1` | | `createdAt` | Filter notes by when it was created | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-02-04T10:48:24Z` | | `updatedAt` | Filter notes by when it was updated | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-02-03T10:48:24Z`| + * Get Notes for a Company + * @param companyId Company\'s ID + * @param [filter] Filter options + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + * @param [totalCount] Include total count of the collection in the pagination response + */ + public v2CompaniesCompanyIdNotesGETWithHttpInfo(companyId: number, filter?: string, cursor?: string, limit?: number, totalCount?: boolean, _options?: PromiseConfigurationOptions): Promise> { + const observableOptions = wrapOptions(_options); + const result = this.api.v2CompaniesCompanyIdNotesGETWithHttpInfo(companyId, filter, cursor, limit, totalCount, observableOptions); + return result.toPromise(); + } + + /** + * | ⚠️ This endpoint is currently in BETA | |--| Returns relevant notes for a given company which includes directly attached notes and notes attached to persons on this company. You can filter notes using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|---------------------------------| | `creator.id` | Filter notes by the creator of the note | `int32` | `=` | `creator.id=1` | | `createdAt` | Filter notes by when it was created | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-02-04T10:48:24Z` | | `updatedAt` | Filter notes by when it was updated | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-02-03T10:48:24Z`| + * Get Notes for a Company + * @param companyId Company\'s ID + * @param [filter] Filter options + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + * @param [totalCount] Include total count of the collection in the pagination response + */ + public v2CompaniesCompanyIdNotesGET(companyId: number, filter?: string, cursor?: string, limit?: number, totalCount?: boolean, _options?: PromiseConfigurationOptions): Promise { + const observableOptions = wrapOptions(_options); + const result = this.api.v2CompaniesCompanyIdNotesGET(companyId, filter, cursor, limit, totalCount, observableOptions); + return result.toPromise(); + } + + /** + * Returns metadata on non-list-specific Company Fields. Use the returned Field IDs to request field data from the GET `/v2/companies` and GET `/v2/companies/{id}` endpoints. + * Get metadata on Company Fields + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + */ + public v2CompaniesFieldsGETWithHttpInfo(cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise> { + const observableOptions = wrapOptions(_options); + const result = this.api.v2CompaniesFieldsGETWithHttpInfo(cursor, limit, observableOptions); + return result.toPromise(); + } + + /** + * Returns metadata on non-list-specific Company Fields. Use the returned Field IDs to request field data from the GET `/v2/companies` and GET `/v2/companies/{id}` endpoints. + * Get metadata on Company Fields + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + */ + public v2CompaniesFieldsGET(cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise { + const observableOptions = wrapOptions(_options); + const result = this.api.v2CompaniesFieldsGET(cursor, limit, observableOptions); + return result.toPromise(); + } + + /** + * Paginate through Companies in Affinity. Returns basic information and non-list-specific field data on each Company. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/companies/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Companies will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All Organizations directory\" [permission](#section/Getting-Started/Permissions). + * Get all Companies + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + * @param [ids] Company IDs + * @param [fieldIds] Field IDs for which to return field data + * @param [fieldTypes] Field Types for which to return field data + */ + public v2CompaniesGETWithHttpInfo(cursor?: string, limit?: number, ids?: Array, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: PromiseConfigurationOptions): Promise> { + const observableOptions = wrapOptions(_options); + const result = this.api.v2CompaniesGETWithHttpInfo(cursor, limit, ids, fieldIds, fieldTypes, observableOptions); + return result.toPromise(); + } + + /** + * Paginate through Companies in Affinity. Returns basic information and non-list-specific field data on each Company. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/companies/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Companies will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All Organizations directory\" [permission](#section/Getting-Started/Permissions). + * Get all Companies + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + * @param [ids] Company IDs + * @param [fieldIds] Field IDs for which to return field data + * @param [fieldTypes] Field Types for which to return field data + */ + public v2CompaniesGET(cursor?: string, limit?: number, ids?: Array, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: PromiseConfigurationOptions): Promise { + const observableOptions = wrapOptions(_options); + const result = this.api.v2CompaniesGET(cursor, limit, ids, fieldIds, fieldTypes, observableOptions); return result.toPromise(); } @@ -418,206 +456,222 @@ export class PromiseCompaniesApi { -import { ObservableListsApi } from './ObservableAPI.ts'; +import { ObservableCompanyMergesApi } from './ObservableAPI.ts'; -import { ListsApiRequestFactory, ListsApiResponseProcessor} from "../apis/ListsApi.ts"; -export class PromiseListsApi { - private api: ObservableListsApi +import { CompanyMergesApiRequestFactory, CompanyMergesApiResponseProcessor} from "../apis/CompanyMergesApi.ts"; +export class PromiseCompanyMergesApi { + private api: ObservableCompanyMergesApi public constructor( configuration: Configuration, - requestFactory?: ListsApiRequestFactory, - responseProcessor?: ListsApiResponseProcessor + requestFactory?: CompanyMergesApiRequestFactory, + responseProcessor?: CompanyMergesApiResponseProcessor ) { - this.api = new ObservableListsApi(configuration, requestFactory, responseProcessor); + this.api = new ObservableCompanyMergesApi(configuration, requestFactory, responseProcessor); } /** - * Returns metadata on the Saved Views on a List. - * Get metadata on Saved Views - * @param listId List ID + * Retrieve paginated company merges for the organization. Returns all company merges initiated by users in your organization, including their current status, the companies involved, and merge details. You can filter company merges using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties: | Property | Type | Operators | Values | Examples | |----------|------|-----------|--------|----------| | `status` | `enum` | `=` | `in-progress`, `success`, `failed` | `status=failed` | | `taskId` | `string` | `=` | | `taskId=789e0123-e45b-67c8-d901-234567890123` | Company merges are returned in reverse chronological order (most recent first). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get All Company Merges * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page + * @param [filter] Filter company merges using Affinity Filtering Language */ - public getV2ListsListidSavedViewsWithHttpInfo(listId: number, cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise> { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } - const result = this.api.getV2ListsListidSavedViewsWithHttpInfo(listId, cursor, limit, observableOptions); + public v2CompanyMergesGETWithHttpInfo(cursor?: string, limit?: number, filter?: string, _options?: PromiseConfigurationOptions): Promise> { + const observableOptions = wrapOptions(_options); + const result = this.api.v2CompanyMergesGETWithHttpInfo(cursor, limit, filter, observableOptions); return result.toPromise(); } /** - * Returns metadata on the Saved Views on a List. - * Get metadata on Saved Views - * @param listId List ID + * Retrieve paginated company merges for the organization. Returns all company merges initiated by users in your organization, including their current status, the companies involved, and merge details. You can filter company merges using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties: | Property | Type | Operators | Values | Examples | |----------|------|-----------|--------|----------| | `status` | `enum` | `=` | `in-progress`, `success`, `failed` | `status=failed` | | `taskId` | `string` | `=` | | `taskId=789e0123-e45b-67c8-d901-234567890123` | Company merges are returned in reverse chronological order (most recent first). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get All Company Merges * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page + * @param [filter] Filter company merges using Affinity Filtering Language */ - public getV2ListsListidSavedViews(listId: number, cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } - const result = this.api.getV2ListsListidSavedViews(listId, cursor, limit, observableOptions); + public v2CompanyMergesGET(cursor?: string, limit?: number, filter?: string, _options?: PromiseConfigurationOptions): Promise { + const observableOptions = wrapOptions(_options); + const result = this.api.v2CompanyMergesGET(cursor, limit, filter, observableOptions); return result.toPromise(); } /** - * Returns metadata on a single Saved View. - * Get metadata on a single Saved View - * @param listId List ID - * @param viewId Saved view ID + * Retrieve the status and details of a specific company merge. Returns information about the company merge including its current status, the companies involved, timestamps, and any error information if the merge failed. The `mergeId` can be obtained from the response of the [Get All Company Merges](#tag/companyMerges/operation/v2_company-merges__GET) endpoint, or by filtering company merges by task ID using `/v2/company-merges?filter=taskId={taskId}` after initiating a merge. Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get Company Merge + * @param mergeId Company merge ID */ - public getV2ListsListidSavedViewsViewidWithHttpInfo(listId: number, viewId: number, _options?: PromiseConfigurationOptions): Promise> { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } - const result = this.api.getV2ListsListidSavedViewsViewidWithHttpInfo(listId, viewId, observableOptions); + public v2CompanyMergesMergeIdGETWithHttpInfo(mergeId: number, _options?: PromiseConfigurationOptions): Promise> { + const observableOptions = wrapOptions(_options); + const result = this.api.v2CompanyMergesMergeIdGETWithHttpInfo(mergeId, observableOptions); return result.toPromise(); } /** - * Returns metadata on a single Saved View. - * Get metadata on a single Saved View - * @param listId List ID - * @param viewId Saved view ID + * Retrieve the status and details of a specific company merge. Returns information about the company merge including its current status, the companies involved, timestamps, and any error information if the merge failed. The `mergeId` can be obtained from the response of the [Get All Company Merges](#tag/companyMerges/operation/v2_company-merges__GET) endpoint, or by filtering company merges by task ID using `/v2/company-merges?filter=taskId={taskId}` after initiating a merge. Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get Company Merge + * @param mergeId Company merge ID */ - public getV2ListsListidSavedViewsViewid(listId: number, viewId: number, _options?: PromiseConfigurationOptions): Promise { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } - const result = this.api.getV2ListsListidSavedViewsViewid(listId, viewId, observableOptions); + public v2CompanyMergesMergeIdGET(mergeId: number, _options?: PromiseConfigurationOptions): Promise { + const observableOptions = wrapOptions(_options); + const result = this.api.v2CompanyMergesMergeIdGET(mergeId, observableOptions); return result.toPromise(); } /** - * Paginate through the List Entries (AKA rows) on a given Saved View. Use this endpoint when you need to filter entities or only want **some** field data to be returned: This endpoint respects the filters set on a Saved View via web app, and only returns field data corresponding to the columns that have been pulled into the Saved View via web app. Though this endpoint respects the Saved View\'s filters and column/Field selection, it does not yet preserve sort order. This endpoint also only supports **sheet-type Saved Views**, and not board- or dashboard-type Saved Views. See the [Data Model](#section/Data-Model) section for more information about Saved Views. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Get all List Entries on a Saved View - * @param listId List ID - * @param viewId Saved view ID + * Initiate a company merge to combine a duplicate company profile into a primary company profile. This is an asynchronous process that will merge all data from the duplicate company into the primary company. Once the merge is initiated, you can track its progress using the returned [task URL](#tag/companyMerges/operation/v2_tasks_company-merges_taskId__GET). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Initiate Company Merge + * @param companyMergeRequest + */ + public v2CompanyMergesPOSTWithHttpInfo(companyMergeRequest: CompanyMergeRequest, _options?: PromiseConfigurationOptions): Promise> { + const observableOptions = wrapOptions(_options); + const result = this.api.v2CompanyMergesPOSTWithHttpInfo(companyMergeRequest, observableOptions); + return result.toPromise(); + } + + /** + * Initiate a company merge to combine a duplicate company profile into a primary company profile. This is an asynchronous process that will merge all data from the duplicate company into the primary company. Once the merge is initiated, you can track its progress using the returned [task URL](#tag/companyMerges/operation/v2_tasks_company-merges_taskId__GET). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Initiate Company Merge + * @param companyMergeRequest + */ + public v2CompanyMergesPOST(companyMergeRequest: CompanyMergeRequest, _options?: PromiseConfigurationOptions): Promise { + const observableOptions = wrapOptions(_options); + const result = this.api.v2CompanyMergesPOST(companyMergeRequest, observableOptions); + return result.toPromise(); + } + + /** + * Retrieve paginated company merge tasks for the organization. Returns all merge tasks initiated by users in your organization, including their current status, the companies involved, and task details. You can filter tasks using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties: | Property | Type | Operators | Values | Examples | |----------|------|-----------|--------|----------| | `status` | `enum` | `=` | `in-progress`, `success`, `failed` | `status=failed` | Tasks are returned in reverse chronological order (most recent first). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get All Company Merge Tasks * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page + * @param [filter] Filter tasks using Affinity Filtering Language */ - public getV2ListsListidSavedViewsViewidListEntriesWithHttpInfo(listId: number, viewId: number, cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise> { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } - const result = this.api.getV2ListsListidSavedViewsViewidListEntriesWithHttpInfo(listId, viewId, cursor, limit, observableOptions); + public v2TasksCompanyMergesGETWithHttpInfo(cursor?: string, limit?: number, filter?: string, _options?: PromiseConfigurationOptions): Promise> { + const observableOptions = wrapOptions(_options); + const result = this.api.v2TasksCompanyMergesGETWithHttpInfo(cursor, limit, filter, observableOptions); return result.toPromise(); } /** - * Paginate through the List Entries (AKA rows) on a given Saved View. Use this endpoint when you need to filter entities or only want **some** field data to be returned: This endpoint respects the filters set on a Saved View via web app, and only returns field data corresponding to the columns that have been pulled into the Saved View via web app. Though this endpoint respects the Saved View\'s filters and column/Field selection, it does not yet preserve sort order. This endpoint also only supports **sheet-type Saved Views**, and not board- or dashboard-type Saved Views. See the [Data Model](#section/Data-Model) section for more information about Saved Views. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Get all List Entries on a Saved View - * @param listId List ID - * @param viewId Saved view ID + * Retrieve paginated company merge tasks for the organization. Returns all merge tasks initiated by users in your organization, including their current status, the companies involved, and task details. You can filter tasks using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties: | Property | Type | Operators | Values | Examples | |----------|------|-----------|--------|----------| | `status` | `enum` | `=` | `in-progress`, `success`, `failed` | `status=failed` | Tasks are returned in reverse chronological order (most recent first). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get All Company Merge Tasks + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + * @param [filter] Filter tasks using Affinity Filtering Language + */ + public v2TasksCompanyMergesGET(cursor?: string, limit?: number, filter?: string, _options?: PromiseConfigurationOptions): Promise { + const observableOptions = wrapOptions(_options); + const result = this.api.v2TasksCompanyMergesGET(cursor, limit, filter, observableOptions); + return result.toPromise(); + } + + /** + * Retrieve the status and details of a specific task for company merges. Returns information about the company merges for a specific task including its overall status, number of merges in-progress, completed, and failed. Detailed information about individual merges for this task can be found by querying: `/v2/company-merges?filter=taskId={taskId}` See [Company Merges](#tag/companyMerges/operation/v2_company-merges__GET) for more details. Task statuses: - `in-progress`: The merge task is currently being processed. - `success`: The merge task completed successfully. - `failed`: The merge task failed. Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get Company Merge Task + * @param taskId Company merge task ID + */ + public v2TasksCompanyMergesTaskIdGETWithHttpInfo(taskId: string, _options?: PromiseConfigurationOptions): Promise> { + const observableOptions = wrapOptions(_options); + const result = this.api.v2TasksCompanyMergesTaskIdGETWithHttpInfo(taskId, observableOptions); + return result.toPromise(); + } + + /** + * Retrieve the status and details of a specific task for company merges. Returns information about the company merges for a specific task including its overall status, number of merges in-progress, completed, and failed. Detailed information about individual merges for this task can be found by querying: `/v2/company-merges?filter=taskId={taskId}` See [Company Merges](#tag/companyMerges/operation/v2_company-merges__GET) for more details. Task statuses: - `in-progress`: The merge task is currently being processed. - `success`: The merge task completed successfully. - `failed`: The merge task failed. Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get Company Merge Task + * @param taskId Company merge task ID + */ + public v2TasksCompanyMergesTaskIdGET(taskId: string, _options?: PromiseConfigurationOptions): Promise { + const observableOptions = wrapOptions(_options); + const result = this.api.v2TasksCompanyMergesTaskIdGET(taskId, observableOptions); + return result.toPromise(); + } + + +} + + + +import { ObservableEmailsApi } from './ObservableAPI.ts'; + +import { EmailsApiRequestFactory, EmailsApiResponseProcessor} from "../apis/EmailsApi.ts"; +export class PromiseEmailsApi { + private api: ObservableEmailsApi + + public constructor( + configuration: Configuration, + requestFactory?: EmailsApiRequestFactory, + responseProcessor?: EmailsApiResponseProcessor + ) { + this.api = new ObservableEmailsApi(configuration, requestFactory, responseProcessor); + } + + /** + * Paginate through all emails in Affinity. Returns basic information about the email interaction and its participants. Will only return emails or subject lines that the current authenticated user has permission to see. You can filter emails using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|----------------------------------| | `id` | Unique identifier for Emails | `int64` | `=` | `id=1` | | `sentAt` | When the Email was sent at | `datetime` | `>`, `<`, `>=`, `<=` | `sentAt>2025-01-01T01:00:00Z` | | `createdAt` | When the Email was created in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-01-01T01:00:00Z` | | `updatedAt` | When the Email was updated in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-01-01T01:00:00Z`| + * Get metadata on all Emails * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page + * @param [filter] Filter options */ - public getV2ListsListidSavedViewsViewidListEntries(listId: number, viewId: number, cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } - const result = this.api.getV2ListsListidSavedViewsViewidListEntries(listId, viewId, cursor, limit, observableOptions); + public v2EmailsGETWithHttpInfo(cursor?: string, limit?: number, filter?: string, _options?: PromiseConfigurationOptions): Promise> { + const observableOptions = wrapOptions(_options); + const result = this.api.v2EmailsGETWithHttpInfo(cursor, limit, filter, observableOptions); return result.toPromise(); } /** - * Returns metadata on Lists. + * Paginate through all emails in Affinity. Returns basic information about the email interaction and its participants. Will only return emails or subject lines that the current authenticated user has permission to see. You can filter emails using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|----------------------------------| | `id` | Unique identifier for Emails | `int64` | `=` | `id=1` | | `sentAt` | When the Email was sent at | `datetime` | `>`, `<`, `>=`, `<=` | `sentAt>2025-01-01T01:00:00Z` | | `createdAt` | When the Email was created in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-01-01T01:00:00Z` | | `updatedAt` | When the Email was updated in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-01-01T01:00:00Z`| + * Get metadata on all Emails + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + * @param [filter] Filter options + */ + public v2EmailsGET(cursor?: string, limit?: number, filter?: string, _options?: PromiseConfigurationOptions): Promise { + const observableOptions = wrapOptions(_options); + const result = this.api.v2EmailsGET(cursor, limit, filter, observableOptions); + return result.toPromise(); + } + + +} + + + +import { ObservableListsApi } from './ObservableAPI.ts'; + +import { ListsApiRequestFactory, ListsApiResponseProcessor} from "../apis/ListsApi.ts"; +export class PromiseListsApi { + private api: ObservableListsApi + + public constructor( + configuration: Configuration, + requestFactory?: ListsApiRequestFactory, + responseProcessor?: ListsApiResponseProcessor + ) { + this.api = new ObservableListsApi(configuration, requestFactory, responseProcessor); + } + + /** + * Paginate through all Lists in your organization that you have access to view. Returns basic information about each List, including name, owner, and privacy settings. * Get metadata on all Lists * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page */ public v2ListsGETWithHttpInfo(cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise> { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } + const observableOptions = wrapOptions(_options); const result = this.api.v2ListsGETWithHttpInfo(cursor, limit, observableOptions); return result.toPromise(); } /** - * Returns metadata on Lists. + * Paginate through all Lists in your organization that you have access to view. Returns basic information about each List, including name, owner, and privacy settings. * Get metadata on all Lists * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page */ public v2ListsGET(cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } + const observableOptions = wrapOptions(_options); const result = this.api.v2ListsGET(cursor, limit, observableOptions); return result.toPromise(); } @@ -630,18 +684,7 @@ export class PromiseListsApi { * @param [limit] Number of items to include in the page */ public v2ListsListIdFieldsGETWithHttpInfo(listId: number, cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise> { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } + const observableOptions = wrapOptions(_options); const result = this.api.v2ListsListIdFieldsGETWithHttpInfo(listId, cursor, limit, observableOptions); return result.toPromise(); } @@ -654,62 +697,29 @@ export class PromiseListsApi { * @param [limit] Number of items to include in the page */ public v2ListsListIdFieldsGET(listId: number, cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } + const observableOptions = wrapOptions(_options); const result = this.api.v2ListsListIdFieldsGET(listId, cursor, limit, observableOptions); return result.toPromise(); } /** - * Returns metadata on a single List. + * Retrieve detailed information about a specific List you have access to view. Returns List configuration including name, owner, privacy settings, and creation details. * Get metadata on a single List * @param listId List ID */ public v2ListsListIdGETWithHttpInfo(listId: number, _options?: PromiseConfigurationOptions): Promise> { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } + const observableOptions = wrapOptions(_options); const result = this.api.v2ListsListIdGETWithHttpInfo(listId, observableOptions); return result.toPromise(); } /** - * Returns metadata on a single List. + * Retrieve detailed information about a specific List you have access to view. Returns List configuration including name, owner, privacy settings, and creation details. * Get metadata on a single List * @param listId List ID */ public v2ListsListIdGET(listId: number, _options?: PromiseConfigurationOptions): Promise { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } + const observableOptions = wrapOptions(_options); const result = this.api.v2ListsListIdGET(listId, observableOptions); return result.toPromise(); } @@ -724,18 +734,7 @@ export class PromiseListsApi { * @param [fieldTypes] Field Types for which to return field data */ public v2ListsListIdListEntriesGETWithHttpInfo(listId: number, cursor?: string, limit?: number, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'list' | 'relationship-intelligence'>, _options?: PromiseConfigurationOptions): Promise> { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } + const observableOptions = wrapOptions(_options); const result = this.api.v2ListsListIdListEntriesGETWithHttpInfo(listId, cursor, limit, fieldIds, fieldTypes, observableOptions); return result.toPromise(); } @@ -750,123 +749,68 @@ export class PromiseListsApi { * @param [fieldTypes] Field Types for which to return field data */ public v2ListsListIdListEntriesGET(listId: number, cursor?: string, limit?: number, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'list' | 'relationship-intelligence'>, _options?: PromiseConfigurationOptions): Promise { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } + const observableOptions = wrapOptions(_options); const result = this.api.v2ListsListIdListEntriesGET(listId, cursor, limit, fieldIds, fieldTypes, observableOptions); return result.toPromise(); } /** - * | ⚠️ This endpoint is currently in BETA | |--| Returns a single field value on a list entry. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Get a single field value [BETA] + * Returns a single field value on a list entry. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Get a single field value * @param listId List ID * @param listEntryId List Entry ID * @param fieldId Field ID */ public v2ListsListIdListEntriesListEntryIdFieldsFieldIdGETWithHttpInfo(listId: number, listEntryId: number, fieldId: string, _options?: PromiseConfigurationOptions): Promise> { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } + const observableOptions = wrapOptions(_options); const result = this.api.v2ListsListIdListEntriesListEntryIdFieldsFieldIdGETWithHttpInfo(listId, listEntryId, fieldId, observableOptions); return result.toPromise(); } /** - * | ⚠️ This endpoint is currently in BETA | |--| Returns a single field value on a list entry. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Get a single field value [BETA] + * Returns a single field value on a list entry. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Get a single field value * @param listId List ID * @param listEntryId List Entry ID * @param fieldId Field ID */ public v2ListsListIdListEntriesListEntryIdFieldsFieldIdGET(listId: number, listEntryId: number, fieldId: string, _options?: PromiseConfigurationOptions): Promise { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } + const observableOptions = wrapOptions(_options); const result = this.api.v2ListsListIdListEntriesListEntryIdFieldsFieldIdGET(listId, listEntryId, fieldId, observableOptions); return result.toPromise(); } /** - * | ⚠️ This endpoint is currently in BETA | |--| Update a single field value. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Update a single field value on a List Entry [BETA] + * Update a single field value. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Update a single field value on a List Entry * @param listId List ID * @param listEntryId List Entry ID * @param fieldId Field ID * @param fieldUpdate */ public v2ListsListIdListEntriesListEntryIdFieldsFieldIdPOSTWithHttpInfo(listId: number, listEntryId: number, fieldId: string, fieldUpdate: FieldUpdate, _options?: PromiseConfigurationOptions): Promise> { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } + const observableOptions = wrapOptions(_options); const result = this.api.v2ListsListIdListEntriesListEntryIdFieldsFieldIdPOSTWithHttpInfo(listId, listEntryId, fieldId, fieldUpdate, observableOptions); return result.toPromise(); } /** - * | ⚠️ This endpoint is currently in BETA | |--| Update a single field value. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Update a single field value on a List Entry [BETA] + * Update a single field value. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Update a single field value on a List Entry * @param listId List ID * @param listEntryId List Entry ID * @param fieldId Field ID * @param fieldUpdate */ public v2ListsListIdListEntriesListEntryIdFieldsFieldIdPOST(listId: number, listEntryId: number, fieldId: string, fieldUpdate: FieldUpdate, _options?: PromiseConfigurationOptions): Promise { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } + const observableOptions = wrapOptions(_options); const result = this.api.v2ListsListIdListEntriesListEntryIdFieldsFieldIdPOST(listId, listEntryId, fieldId, fieldUpdate, observableOptions); return result.toPromise(); } /** - * | ⚠️ This endpoint is currently in BETA | |--| Paginate through all field values on a single list entry. All fields will be included by default. The `ids` and `types` parameters can be used to filter the collection. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Get field values on a single List Entry [BETA] + * Paginate through all field values on a single list entry. All fields will be included by default. The `ids` and `types` parameters can be used to filter the collection. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Get field values on a single List Entry * @param listId List ID * @param listEntryId List Entry ID * @param [ids] Field IDs for which to return field data @@ -875,25 +819,14 @@ export class PromiseListsApi { * @param [limit] Number of items to include in the page */ public v2ListsListIdListEntriesListEntryIdFieldsGETWithHttpInfo(listId: number, listEntryId: number, ids?: Array, types?: Array<'enriched' | 'global' | 'list' | 'relationship-intelligence'>, cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise> { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } + const observableOptions = wrapOptions(_options); const result = this.api.v2ListsListIdListEntriesListEntryIdFieldsGETWithHttpInfo(listId, listEntryId, ids, types, cursor, limit, observableOptions); return result.toPromise(); } /** - * | ⚠️ This endpoint is currently in BETA | |--| Paginate through all field values on a single list entry. All fields will be included by default. The `ids` and `types` parameters can be used to filter the collection. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Get field values on a single List Entry [BETA] + * Paginate through all field values on a single list entry. All fields will be included by default. The `ids` and `types` parameters can be used to filter the collection. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Get field values on a single List Entry * @param listId List ID * @param listEntryId List Entry ID * @param [ids] Field IDs for which to return field data @@ -902,120 +835,375 @@ export class PromiseListsApi { * @param [limit] Number of items to include in the page */ public v2ListsListIdListEntriesListEntryIdFieldsGET(listId: number, listEntryId: number, ids?: Array, types?: Array<'enriched' | 'global' | 'list' | 'relationship-intelligence'>, cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } + const observableOptions = wrapOptions(_options); const result = this.api.v2ListsListIdListEntriesListEntryIdFieldsGET(listId, listEntryId, ids, types, cursor, limit, observableOptions); return result.toPromise(); } /** - * | ⚠️ This endpoint is currently in BETA | |--| Perform batch operations on a list entry\'s fields. Currently the only operation at the endpoint is `update-fields`, which allows you to update multiple field values with a single request. This is equivalent to calling [the single field update](#operation/v2_lists_listId_list-entries_listEntryId_fields_fieldId__POST) endpoint multiple times. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Perform batch operations on a list entry\'s fields [BETA] + * Perform batch operations on a list entry\'s fields. Currently the only operation at the endpoint is `update-fields`, which allows you to update multiple field values with a single request. This is equivalent to calling [the single field update](#operation/v2_lists_listId_list-entries_listEntryId_fields_fieldId__POST) endpoint multiple times. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Perform batch operations on a list entry\'s fields * @param listId List ID * @param listEntryId List Entry ID * @param body */ public v2ListsListIdListEntriesListEntryIdFieldsPATCHWithHttpInfo(listId: number, listEntryId: number, body: ListEntryBatchOperationUpdateFields, _options?: PromiseConfigurationOptions): Promise> { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } + const observableOptions = wrapOptions(_options); const result = this.api.v2ListsListIdListEntriesListEntryIdFieldsPATCHWithHttpInfo(listId, listEntryId, body, observableOptions); return result.toPromise(); } /** - * | ⚠️ This endpoint is currently in BETA | |--| Perform batch operations on a list entry\'s fields. Currently the only operation at the endpoint is `update-fields`, which allows you to update multiple field values with a single request. This is equivalent to calling [the single field update](#operation/v2_lists_listId_list-entries_listEntryId_fields_fieldId__POST) endpoint multiple times. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Perform batch operations on a list entry\'s fields [BETA] + * Perform batch operations on a list entry\'s fields. Currently the only operation at the endpoint is `update-fields`, which allows you to update multiple field values with a single request. This is equivalent to calling [the single field update](#operation/v2_lists_listId_list-entries_listEntryId_fields_fieldId__POST) endpoint multiple times. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Perform batch operations on a list entry\'s fields * @param listId List ID * @param listEntryId List Entry ID * @param body */ public v2ListsListIdListEntriesListEntryIdFieldsPATCH(listId: number, listEntryId: number, body: ListEntryBatchOperationUpdateFields, _options?: PromiseConfigurationOptions): Promise { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } + const observableOptions = wrapOptions(_options); const result = this.api.v2ListsListIdListEntriesListEntryIdFieldsPATCH(listId, listEntryId, body, observableOptions); return result.toPromise(); } /** - * | ⚠️ This endpoint is currently in BETA | |--| Retrieve a single list entry. Returns basic information and field data, including list-specific field data. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/lists/{listId}/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, the List Entry will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Get a single List Entry on a List [BETA] + * Retrieve a single list entry. Returns basic information and field data, including list-specific field data. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/lists/{listId}/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, the List Entry will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Get a single List Entry on a List * @param listId List ID * @param listEntryId List Entry ID * @param [fieldIds] Field IDs for which to return field data * @param [fieldTypes] Field Types for which to return field data */ public v2ListsListIdListEntriesListEntryIdGETWithHttpInfo(listId: number, listEntryId: number, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'list' | 'relationship-intelligence'>, _options?: PromiseConfigurationOptions): Promise> { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } + const observableOptions = wrapOptions(_options); const result = this.api.v2ListsListIdListEntriesListEntryIdGETWithHttpInfo(listId, listEntryId, fieldIds, fieldTypes, observableOptions); return result.toPromise(); } /** - * | ⚠️ This endpoint is currently in BETA | |--| Retrieve a single list entry. Returns basic information and field data, including list-specific field data. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/lists/{listId}/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, the List Entry will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). - * Get a single List Entry on a List [BETA] + * Retrieve a single list entry. Returns basic information and field data, including list-specific field data. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/lists/{listId}/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, the List Entry will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Get a single List Entry on a List * @param listId List ID * @param listEntryId List Entry ID * @param [fieldIds] Field IDs for which to return field data * @param [fieldTypes] Field Types for which to return field data */ public v2ListsListIdListEntriesListEntryIdGET(listId: number, listEntryId: number, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'list' | 'relationship-intelligence'>, _options?: PromiseConfigurationOptions): Promise { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } + const observableOptions = wrapOptions(_options); const result = this.api.v2ListsListIdListEntriesListEntryIdGET(listId, listEntryId, fieldIds, fieldTypes, observableOptions); return result.toPromise(); } + /** + * Paginate through all Saved Views you have access to view for a specific List. Returns Saved View configurations including name, column settings, and owner information. + * Get metadata on Saved Views + * @param listId List ID + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + */ + public v2ListsListIdSavedViewsGETWithHttpInfo(listId: number, cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise> { + const observableOptions = wrapOptions(_options); + const result = this.api.v2ListsListIdSavedViewsGETWithHttpInfo(listId, cursor, limit, observableOptions); + return result.toPromise(); + } + + /** + * Paginate through all Saved Views you have access to view for a specific List. Returns Saved View configurations including name, column settings, and owner information. + * Get metadata on Saved Views + * @param listId List ID + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + */ + public v2ListsListIdSavedViewsGET(listId: number, cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise { + const observableOptions = wrapOptions(_options); + const result = this.api.v2ListsListIdSavedViewsGET(listId, cursor, limit, observableOptions); + return result.toPromise(); + } + + /** + * Retrieve detailed information about a specific Saved View you have access to view. Returns complete Saved View configuration including name, sorting, and column visibility settings. + * Get metadata on a single Saved View + * @param listId List ID + * @param viewId Saved view ID + */ + public v2ListsListIdSavedViewsViewIdGETWithHttpInfo(listId: number, viewId: number, _options?: PromiseConfigurationOptions): Promise> { + const observableOptions = wrapOptions(_options); + const result = this.api.v2ListsListIdSavedViewsViewIdGETWithHttpInfo(listId, viewId, observableOptions); + return result.toPromise(); + } + + /** + * Retrieve detailed information about a specific Saved View you have access to view. Returns complete Saved View configuration including name, sorting, and column visibility settings. + * Get metadata on a single Saved View + * @param listId List ID + * @param viewId Saved view ID + */ + public v2ListsListIdSavedViewsViewIdGET(listId: number, viewId: number, _options?: PromiseConfigurationOptions): Promise { + const observableOptions = wrapOptions(_options); + const result = this.api.v2ListsListIdSavedViewsViewIdGET(listId, viewId, observableOptions); + return result.toPromise(); + } + + /** + * Paginate through the List Entries (AKA rows) on a given Saved View. Use this endpoint when you need to filter entities or only want **some** field data to be returned: This endpoint respects the filters set on a Saved View via web app, and only returns field data corresponding to the columns that have been pulled into the Saved View via web app. Though this endpoint respects the Saved View\'s filters and column/Field selection, it does not yet preserve sort order. This endpoint also only supports **sheet-type Saved Views**, and not board- or dashboard-type Saved Views. See the [Data Model](#section/Data-Model) section for more information about Saved Views. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Get all List Entries on a Saved View + * @param listId List ID + * @param viewId Saved view ID + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + */ + public v2ListsListIdSavedViewsViewIdListEntriesGETWithHttpInfo(listId: number, viewId: number, cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise> { + const observableOptions = wrapOptions(_options); + const result = this.api.v2ListsListIdSavedViewsViewIdListEntriesGETWithHttpInfo(listId, viewId, cursor, limit, observableOptions); + return result.toPromise(); + } + + /** + * Paginate through the List Entries (AKA rows) on a given Saved View. Use this endpoint when you need to filter entities or only want **some** field data to be returned: This endpoint respects the filters set on a Saved View via web app, and only returns field data corresponding to the columns that have been pulled into the Saved View via web app. Though this endpoint respects the Saved View\'s filters and column/Field selection, it does not yet preserve sort order. This endpoint also only supports **sheet-type Saved Views**, and not board- or dashboard-type Saved Views. See the [Data Model](#section/Data-Model) section for more information about Saved Views. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). + * Get all List Entries on a Saved View + * @param listId List ID + * @param viewId Saved view ID + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + */ + public v2ListsListIdSavedViewsViewIdListEntriesGET(listId: number, viewId: number, cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise { + const observableOptions = wrapOptions(_options); + const result = this.api.v2ListsListIdSavedViewsViewIdListEntriesGET(listId, viewId, cursor, limit, observableOptions); + return result.toPromise(); + } + + +} + + + +import { ObservableMeetingsApi } from './ObservableAPI.ts'; + +import { MeetingsApiRequestFactory, MeetingsApiResponseProcessor} from "../apis/MeetingsApi.ts"; +export class PromiseMeetingsApi { + private api: ObservableMeetingsApi + + public constructor( + configuration: Configuration, + requestFactory?: MeetingsApiRequestFactory, + responseProcessor?: MeetingsApiResponseProcessor + ) { + this.api = new ObservableMeetingsApi(configuration, requestFactory, responseProcessor); + } + + /** + * Paginate through all Meetings in Affinity. Returns basic information about past and future meeting interactions and its attendees. You can filter meetings using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|----------------------------------| | `id` | Unique identifier for Meetings | `int64` | `=` | `id=1` | | `startTime` | Start time of when Meeting was scheduled | `datetime` | `>`, `<`, `>=`, `<=` | `startTime>2025-01-01T01:00:00Z` | | `createdAt` | When the Meeting was created in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-01-01T01:00:00Z` | | `updatedAt` | When the Meeting was updated in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-01-01T01:00:00Z`| + * Get metadata on all Meetings + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + * @param [filter] Filter options + */ + public v2MeetingsGETWithHttpInfo(cursor?: string, limit?: number, filter?: string, _options?: PromiseConfigurationOptions): Promise> { + const observableOptions = wrapOptions(_options); + const result = this.api.v2MeetingsGETWithHttpInfo(cursor, limit, filter, observableOptions); + return result.toPromise(); + } + + /** + * Paginate through all Meetings in Affinity. Returns basic information about past and future meeting interactions and its attendees. You can filter meetings using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|----------------------------------| | `id` | Unique identifier for Meetings | `int64` | `=` | `id=1` | | `startTime` | Start time of when Meeting was scheduled | `datetime` | `>`, `<`, `>=`, `<=` | `startTime>2025-01-01T01:00:00Z` | | `createdAt` | When the Meeting was created in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-01-01T01:00:00Z` | | `updatedAt` | When the Meeting was updated in Affinity | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-01-01T01:00:00Z`| + * Get metadata on all Meetings + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + * @param [filter] Filter options + */ + public v2MeetingsGET(cursor?: string, limit?: number, filter?: string, _options?: PromiseConfigurationOptions): Promise { + const observableOptions = wrapOptions(_options); + const result = this.api.v2MeetingsGET(cursor, limit, filter, observableOptions); + return result.toPromise(); + } + + +} + + + +import { ObservableNotesApi } from './ObservableAPI.ts'; + +import { NotesApiRequestFactory, NotesApiResponseProcessor} from "../apis/NotesApi.ts"; +export class PromiseNotesApi { + private api: ObservableNotesApi + + public constructor( + configuration: Configuration, + requestFactory?: NotesApiRequestFactory, + responseProcessor?: NotesApiResponseProcessor + ) { + this.api = new ObservableNotesApi(configuration, requestFactory, responseProcessor); + } + + /** + * | ⚠️ This endpoint is currently in BETA | |--| Returns all notes, with the exception of replies. You can filter notes using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|---------------------------------| | `id` | Filter notes by id | `int32` | `=` | `id=1` | | `creator.id` | Filter notes by the creator of the note | `int32` | `=` | `creator.id=1` | | `createdAt` | Filter notes by when it was created | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-02-04T10:48:24Z` | | `updatedAt` | Filter notes by when it was updated | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-02-03T10:48:24Z`| + * Get all Notes + * @param [totalCount] Include total count of the collection in the pagination response + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + * @param [filter] Filter options + * @param [includes] Additional properties to include in the response + */ + public v2NotesGETWithHttpInfo(totalCount?: boolean, cursor?: string, limit?: number, filter?: string, includes?: Set<'companiesPreview' | 'personsPreview' | 'opportunitiesPreview' | 'repliesCount'>, _options?: PromiseConfigurationOptions): Promise> { + const observableOptions = wrapOptions(_options); + const result = this.api.v2NotesGETWithHttpInfo(totalCount, cursor, limit, filter, includes, observableOptions); + return result.toPromise(); + } + + /** + * | ⚠️ This endpoint is currently in BETA | |--| Returns all notes, with the exception of replies. You can filter notes using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|---------------------------------| | `id` | Filter notes by id | `int32` | `=` | `id=1` | | `creator.id` | Filter notes by the creator of the note | `int32` | `=` | `creator.id=1` | | `createdAt` | Filter notes by when it was created | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-02-04T10:48:24Z` | | `updatedAt` | Filter notes by when it was updated | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-02-03T10:48:24Z`| + * Get all Notes + * @param [totalCount] Include total count of the collection in the pagination response + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + * @param [filter] Filter options + * @param [includes] Additional properties to include in the response + */ + public v2NotesGET(totalCount?: boolean, cursor?: string, limit?: number, filter?: string, includes?: Set<'companiesPreview' | 'personsPreview' | 'opportunitiesPreview' | 'repliesCount'>, _options?: PromiseConfigurationOptions): Promise { + const observableOptions = wrapOptions(_options); + const result = this.api.v2NotesGET(totalCount, cursor, limit, filter, includes, observableOptions); + return result.toPromise(); + } + + /** + * | ⚠️ This endpoint is currently in BETA | |--| Returns directly attached companies for a given Note. + * Get Companies attached to a Note + * @param noteId The id of the Note to get attached Companies + * @param [totalCount] Include total count of the collection in the pagination response + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + */ + public v2NotesNoteIdAttachedCompaniesGETWithHttpInfo(noteId: number, totalCount?: boolean, cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise> { + const observableOptions = wrapOptions(_options); + const result = this.api.v2NotesNoteIdAttachedCompaniesGETWithHttpInfo(noteId, totalCount, cursor, limit, observableOptions); + return result.toPromise(); + } + + /** + * | ⚠️ This endpoint is currently in BETA | |--| Returns directly attached companies for a given Note. + * Get Companies attached to a Note + * @param noteId The id of the Note to get attached Companies + * @param [totalCount] Include total count of the collection in the pagination response + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + */ + public v2NotesNoteIdAttachedCompaniesGET(noteId: number, totalCount?: boolean, cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise { + const observableOptions = wrapOptions(_options); + const result = this.api.v2NotesNoteIdAttachedCompaniesGET(noteId, totalCount, cursor, limit, observableOptions); + return result.toPromise(); + } + + /** + * | ⚠️ This endpoint is currently in BETA | |--| Returns directly attached opportunities for a given Note. + * Get Opportunities attached to a Note + * @param noteId The id of the Note to get attached Opportunities + * @param [totalCount] Include total count of the collection in the pagination response + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + */ + public v2NotesNoteIdAttachedOpportunitiesGETWithHttpInfo(noteId: number, totalCount?: boolean, cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise> { + const observableOptions = wrapOptions(_options); + const result = this.api.v2NotesNoteIdAttachedOpportunitiesGETWithHttpInfo(noteId, totalCount, cursor, limit, observableOptions); + return result.toPromise(); + } + + /** + * | ⚠️ This endpoint is currently in BETA | |--| Returns directly attached opportunities for a given Note. + * Get Opportunities attached to a Note + * @param noteId The id of the Note to get attached Opportunities + * @param [totalCount] Include total count of the collection in the pagination response + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + */ + public v2NotesNoteIdAttachedOpportunitiesGET(noteId: number, totalCount?: boolean, cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise { + const observableOptions = wrapOptions(_options); + const result = this.api.v2NotesNoteIdAttachedOpportunitiesGET(noteId, totalCount, cursor, limit, observableOptions); + return result.toPromise(); + } + + /** + * | ⚠️ This endpoint is currently in BETA | |--| Returns directly attached persons for a given Note. + * Get Persons attached to a Note + * @param noteId The id of the Note to get attached Persons + * @param [totalCount] Include total count of the collection in the pagination response + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + */ + public v2NotesNoteIdAttachedPersonsGETWithHttpInfo(noteId: number, totalCount?: boolean, cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise> { + const observableOptions = wrapOptions(_options); + const result = this.api.v2NotesNoteIdAttachedPersonsGETWithHttpInfo(noteId, totalCount, cursor, limit, observableOptions); + return result.toPromise(); + } + + /** + * | ⚠️ This endpoint is currently in BETA | |--| Returns directly attached persons for a given Note. + * Get Persons attached to a Note + * @param noteId The id of the Note to get attached Persons + * @param [totalCount] Include total count of the collection in the pagination response + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + */ + public v2NotesNoteIdAttachedPersonsGET(noteId: number, totalCount?: boolean, cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise { + const observableOptions = wrapOptions(_options); + const result = this.api.v2NotesNoteIdAttachedPersonsGET(noteId, totalCount, cursor, limit, observableOptions); + return result.toPromise(); + } + + /** + * | ⚠️ This endpoint is currently in BETA | |--| Get a Note with a given id + * Get a single Note + * @param noteId The id of the Note + * @param [includes] Additional properties to include in the response + */ + public v2NotesNoteIdGETWithHttpInfo(noteId: number, includes?: Set<'companiesPreview' | 'personsPreview' | 'opportunitiesPreview' | 'repliesCount'>, _options?: PromiseConfigurationOptions): Promise> { + const observableOptions = wrapOptions(_options); + const result = this.api.v2NotesNoteIdGETWithHttpInfo(noteId, includes, observableOptions); + return result.toPromise(); + } + + /** + * | ⚠️ This endpoint is currently in BETA | |--| Get a Note with a given id + * Get a single Note + * @param noteId The id of the Note + * @param [includes] Additional properties to include in the response + */ + public v2NotesNoteIdGET(noteId: number, includes?: Set<'companiesPreview' | 'personsPreview' | 'opportunitiesPreview' | 'repliesCount'>, _options?: PromiseConfigurationOptions): Promise { + const observableOptions = wrapOptions(_options); + const result = this.api.v2NotesNoteIdGET(noteId, includes, observableOptions); + return result.toPromise(); + } + + /** + * | ⚠️ This endpoint is currently in BETA | |--| This endpoint returns reply notes for a given note id. You can filter replies using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|---------------------------------| | `creator.id` | Filter notes by the creator of the note | `int32` | `=` | `creator.id=1` | | `createdAt` | Filter notes by when it was created | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-02-04T10:48:24Z` | | `updatedAt` | Filter notes by when it was updated | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-02-03T10:48:24Z`| + * Get replies for a Note + * @param noteId Note ID + * @param [filter] Filter options + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + * @param [totalCount] Include total count of the collection in the pagination response + */ + public v2NotesNoteIdRepliesGETWithHttpInfo(noteId: number, filter?: string, cursor?: string, limit?: number, totalCount?: boolean, _options?: PromiseConfigurationOptions): Promise> { + const observableOptions = wrapOptions(_options); + const result = this.api.v2NotesNoteIdRepliesGETWithHttpInfo(noteId, filter, cursor, limit, totalCount, observableOptions); + return result.toPromise(); + } + + /** + * | ⚠️ This endpoint is currently in BETA | |--| This endpoint returns reply notes for a given note id. You can filter replies using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|---------------------------------| | `creator.id` | Filter notes by the creator of the note | `int32` | `=` | `creator.id=1` | | `createdAt` | Filter notes by when it was created | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-02-04T10:48:24Z` | | `updatedAt` | Filter notes by when it was updated | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-02-03T10:48:24Z`| + * Get replies for a Note + * @param noteId Note ID + * @param [filter] Filter options + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + * @param [totalCount] Include total count of the collection in the pagination response + */ + public v2NotesNoteIdRepliesGET(noteId: number, filter?: string, cursor?: string, limit?: number, totalCount?: boolean, _options?: PromiseConfigurationOptions): Promise { + const observableOptions = wrapOptions(_options); + const result = this.api.v2NotesNoteIdRepliesGET(noteId, filter, cursor, limit, totalCount, observableOptions); + return result.toPromise(); + } + } @@ -1042,20 +1230,9 @@ export class PromiseOpportunitiesApi { * @param [limit] Number of items to include in the page * @param [ids] Opportunity IDs */ - public getV2OpportunitiesWithHttpInfo(cursor?: string, limit?: number, ids?: Array, _options?: PromiseConfigurationOptions): Promise> { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } - const result = this.api.getV2OpportunitiesWithHttpInfo(cursor, limit, ids, observableOptions); + public v2OpportunitiesGETWithHttpInfo(cursor?: string, limit?: number, ids?: Array, _options?: PromiseConfigurationOptions): Promise> { + const observableOptions = wrapOptions(_options); + const result = this.api.v2OpportunitiesGETWithHttpInfo(cursor, limit, ids, observableOptions); return result.toPromise(); } @@ -1066,64 +1243,198 @@ export class PromiseOpportunitiesApi { * @param [limit] Number of items to include in the page * @param [ids] Opportunity IDs */ - public getV2Opportunities(cursor?: string, limit?: number, ids?: Array, _options?: PromiseConfigurationOptions): Promise { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } - const result = this.api.getV2Opportunities(cursor, limit, ids, observableOptions); + public v2OpportunitiesGET(cursor?: string, limit?: number, ids?: Array, _options?: PromiseConfigurationOptions): Promise { + const observableOptions = wrapOptions(_options); + const result = this.api.v2OpportunitiesGET(cursor, limit, ids, observableOptions); return result.toPromise(); } /** * Returns basic information but **not** field data on the requested Opportunity. To access field data on Opportunities, use the `/lists/{list_id}/list-entries` or the `/v2/lists/{list_id}/saved-views/{view_id}/list-entries` GET endpoint. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). * Get a single Opportunity - * @param id Opportunity ID + * @param opportunityId Opportunity ID */ - public getV2OpportunitiesIdWithHttpInfo(id: number, _options?: PromiseConfigurationOptions): Promise> { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } - const result = this.api.getV2OpportunitiesIdWithHttpInfo(id, observableOptions); + public v2OpportunitiesOpportunityIdGETWithHttpInfo(opportunityId: number, _options?: PromiseConfigurationOptions): Promise> { + const observableOptions = wrapOptions(_options); + const result = this.api.v2OpportunitiesOpportunityIdGETWithHttpInfo(opportunityId, observableOptions); return result.toPromise(); } /** * Returns basic information but **not** field data on the requested Opportunity. To access field data on Opportunities, use the `/lists/{list_id}/list-entries` or the `/v2/lists/{list_id}/saved-views/{view_id}/list-entries` GET endpoint. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). * Get a single Opportunity - * @param id Opportunity ID + * @param opportunityId Opportunity ID */ - public getV2OpportunitiesId(id: number, _options?: PromiseConfigurationOptions): Promise { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } - const result = this.api.getV2OpportunitiesId(id, observableOptions); + public v2OpportunitiesOpportunityIdGET(opportunityId: number, _options?: PromiseConfigurationOptions): Promise { + const observableOptions = wrapOptions(_options); + const result = this.api.v2OpportunitiesOpportunityIdGET(opportunityId, observableOptions); + return result.toPromise(); + } + + /** + * | ⚠️ This endpoint is currently in BETA | |--| Returns Notes for a given Opportunity which includes directly attached notes and those attached to persons on this Opportunity. You can filter notes using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|---------------------------------| | `creator.id` | Filter notes by the creator of the note | `int32` | `=` | `creator.id=1` | | `createdAt` | Filter notes by when it was created | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-02-04T10:48:24Z` | | `updatedAt` | Filter notes by when it was updated | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-02-03T10:48:24Z`| + * Get Notes for an Opportunity + * @param opportunityId Opportunity ID + * @param [filter] Filter options + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + * @param [totalCount] Include total count of the collection in the pagination response + */ + public v2OpportunitiesOpportunityIdNotesGETWithHttpInfo(opportunityId: number, filter?: string, cursor?: string, limit?: number, totalCount?: boolean, _options?: PromiseConfigurationOptions): Promise> { + const observableOptions = wrapOptions(_options); + const result = this.api.v2OpportunitiesOpportunityIdNotesGETWithHttpInfo(opportunityId, filter, cursor, limit, totalCount, observableOptions); + return result.toPromise(); + } + + /** + * | ⚠️ This endpoint is currently in BETA | |--| Returns Notes for a given Opportunity which includes directly attached notes and those attached to persons on this Opportunity. You can filter notes using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|---------------------------------| | `creator.id` | Filter notes by the creator of the note | `int32` | `=` | `creator.id=1` | | `createdAt` | Filter notes by when it was created | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-02-04T10:48:24Z` | | `updatedAt` | Filter notes by when it was updated | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-02-03T10:48:24Z`| + * Get Notes for an Opportunity + * @param opportunityId Opportunity ID + * @param [filter] Filter options + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + * @param [totalCount] Include total count of the collection in the pagination response + */ + public v2OpportunitiesOpportunityIdNotesGET(opportunityId: number, filter?: string, cursor?: string, limit?: number, totalCount?: boolean, _options?: PromiseConfigurationOptions): Promise { + const observableOptions = wrapOptions(_options); + const result = this.api.v2OpportunitiesOpportunityIdNotesGET(opportunityId, filter, cursor, limit, totalCount, observableOptions); + return result.toPromise(); + } + + +} + + + +import { ObservablePersonMergesApi } from './ObservableAPI.ts'; + +import { PersonMergesApiRequestFactory, PersonMergesApiResponseProcessor} from "../apis/PersonMergesApi.ts"; +export class PromisePersonMergesApi { + private api: ObservablePersonMergesApi + + public constructor( + configuration: Configuration, + requestFactory?: PersonMergesApiRequestFactory, + responseProcessor?: PersonMergesApiResponseProcessor + ) { + this.api = new ObservablePersonMergesApi(configuration, requestFactory, responseProcessor); + } + + /** + * Retrieve paginated person merges for the organization. Returns all person merges initiated by users in your organization, including their current status, the persons involved, and merge details. You can filter person merges using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties: | Property | Type | Operators | Values | Examples | |----------|------|-----------|--------|----------| | `status` | `enum` | `=` | `in-progress`, `success`, `failed` | `status=failed` | | `taskId` | `string` | `=` | | `taskId=789e0123-e45b-67c8-d901-234567890123` | Person merges are returned in reverse chronological order (most recent first). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get All Person Merges + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + * @param [filter] Filter person merges using Affinity Filtering Language + */ + public v2PersonMergesGETWithHttpInfo(cursor?: string, limit?: number, filter?: string, _options?: PromiseConfigurationOptions): Promise> { + const observableOptions = wrapOptions(_options); + const result = this.api.v2PersonMergesGETWithHttpInfo(cursor, limit, filter, observableOptions); + return result.toPromise(); + } + + /** + * Retrieve paginated person merges for the organization. Returns all person merges initiated by users in your organization, including their current status, the persons involved, and merge details. You can filter person merges using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties: | Property | Type | Operators | Values | Examples | |----------|------|-----------|--------|----------| | `status` | `enum` | `=` | `in-progress`, `success`, `failed` | `status=failed` | | `taskId` | `string` | `=` | | `taskId=789e0123-e45b-67c8-d901-234567890123` | Person merges are returned in reverse chronological order (most recent first). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get All Person Merges + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + * @param [filter] Filter person merges using Affinity Filtering Language + */ + public v2PersonMergesGET(cursor?: string, limit?: number, filter?: string, _options?: PromiseConfigurationOptions): Promise { + const observableOptions = wrapOptions(_options); + const result = this.api.v2PersonMergesGET(cursor, limit, filter, observableOptions); + return result.toPromise(); + } + + /** + * Retrieve the status and details of a specific person merge. Returns information about the person merge including its current status, the persons involved, timestamps, and any error information if the merge failed. The `mergeId` can be obtained from the response of the [Get All Person Merges](#tag/personMerges/operation/v2_person-merges__GET) endpoint, or by filtering person merges by task ID using `/v2/person-merges?filter=taskId={taskId}` after initiating a merge. Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get Person Merge + * @param mergeId Person merge ID + */ + public v2PersonMergesMergeIdGETWithHttpInfo(mergeId: number, _options?: PromiseConfigurationOptions): Promise> { + const observableOptions = wrapOptions(_options); + const result = this.api.v2PersonMergesMergeIdGETWithHttpInfo(mergeId, observableOptions); + return result.toPromise(); + } + + /** + * Retrieve the status and details of a specific person merge. Returns information about the person merge including its current status, the persons involved, timestamps, and any error information if the merge failed. The `mergeId` can be obtained from the response of the [Get All Person Merges](#tag/personMerges/operation/v2_person-merges__GET) endpoint, or by filtering person merges by task ID using `/v2/person-merges?filter=taskId={taskId}` after initiating a merge. Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get Person Merge + * @param mergeId Person merge ID + */ + public v2PersonMergesMergeIdGET(mergeId: number, _options?: PromiseConfigurationOptions): Promise { + const observableOptions = wrapOptions(_options); + const result = this.api.v2PersonMergesMergeIdGET(mergeId, observableOptions); + return result.toPromise(); + } + + /** + * Initiate a person merge to combine a duplicate person profile into a primary person profile. This is an asynchronous process that will merge all data from the duplicate person into the primary person. Once the merge is initiated, you can track its progress using the returned [task URL](#tag/personMerges/operation/v2_tasks_person-merges_taskId__GET). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Initiate Person Merge + * @param personMergeRequest + */ + public v2PersonMergesPOSTWithHttpInfo(personMergeRequest: PersonMergeRequest, _options?: PromiseConfigurationOptions): Promise> { + const observableOptions = wrapOptions(_options); + const result = this.api.v2PersonMergesPOSTWithHttpInfo(personMergeRequest, observableOptions); + return result.toPromise(); + } + + /** + * Initiate a person merge to combine a duplicate person profile into a primary person profile. This is an asynchronous process that will merge all data from the duplicate person into the primary person. Once the merge is initiated, you can track its progress using the returned [task URL](#tag/personMerges/operation/v2_tasks_person-merges_taskId__GET). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Initiate Person Merge + * @param personMergeRequest + */ + public v2PersonMergesPOST(personMergeRequest: PersonMergeRequest, _options?: PromiseConfigurationOptions): Promise { + const observableOptions = wrapOptions(_options); + const result = this.api.v2PersonMergesPOST(personMergeRequest, observableOptions); + return result.toPromise(); + } + + /** + * Retrieve paginated person merge tasks for the organization. Returns all merge tasks initiated by users in your organization, including their current status, the persons involved, and task details. You can filter tasks using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties: | Property | Type | Operators | Values | Examples | |----------|------|-----------|--------|----------| | `status` | `enum` | `=` | `in-progress`, `success`, `failed` | `status=failed` | Tasks are returned in reverse chronological order (most recent first). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get All Person Merge Tasks + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + * @param [filter] Filter tasks using Affinity Filtering Language + */ + public v2TasksPersonMergesGETWithHttpInfo(cursor?: string, limit?: number, filter?: string, _options?: PromiseConfigurationOptions): Promise> { + const observableOptions = wrapOptions(_options); + const result = this.api.v2TasksPersonMergesGETWithHttpInfo(cursor, limit, filter, observableOptions); + return result.toPromise(); + } + + /** + * Retrieve paginated person merge tasks for the organization. Returns all merge tasks initiated by users in your organization, including their current status, the persons involved, and task details. You can filter tasks using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties: | Property | Type | Operators | Values | Examples | |----------|------|-----------|--------|----------| | `status` | `enum` | `=` | `in-progress`, `success`, `failed` | `status=failed` | Tasks are returned in reverse chronological order (most recent first). Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get All Person Merge Tasks + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + * @param [filter] Filter tasks using Affinity Filtering Language + */ + public v2TasksPersonMergesGET(cursor?: string, limit?: number, filter?: string, _options?: PromiseConfigurationOptions): Promise { + const observableOptions = wrapOptions(_options); + const result = this.api.v2TasksPersonMergesGET(cursor, limit, filter, observableOptions); + return result.toPromise(); + } + + /** + * Retrieve the status and details of a specific task for person merges. Returns information about the person merges for a specific task including its overall status, number of merges in-progress, completed, and failed. Detailed information about individual merges for this task can be found by querying: `/v2/person-merges?filter=taskId={taskId}` See [Person Merges](#tag/personMerges/operation/v2_person-merges__GET) for more details. Task statuses: - `in-progress`: The merge task is currently being processed. - `success`: The merge task completed successfully. - `failed`: The merge task failed. Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get Person Merge Task + * @param taskId Person merge task ID + */ + public v2TasksPersonMergesTaskIdGETWithHttpInfo(taskId: string, _options?: PromiseConfigurationOptions): Promise> { + const observableOptions = wrapOptions(_options); + const result = this.api.v2TasksPersonMergesTaskIdGETWithHttpInfo(taskId, observableOptions); + return result.toPromise(); + } + + /** + * Retrieve the status and details of a specific task for person merges. Returns information about the person merges for a specific task including its overall status, number of merges in-progress, completed, and failed. Detailed information about individual merges for this task can be found by querying: `/v2/person-merges?filter=taskId={taskId}` See [Person Merges](#tag/personMerges/operation/v2_person-merges__GET) for more details. Task statuses: - `in-progress`: The merge task is currently being processed. - `success`: The merge task completed successfully. - `failed`: The merge task failed. Requires the \"Manage duplicates\" [permission](#section/Getting-Started/Permissions) and organization admin role. + * Get Person Merge Task + * @param taskId Person merge task ID + */ + public v2TasksPersonMergesTaskIdGET(taskId: string, _options?: PromiseConfigurationOptions): Promise { + const observableOptions = wrapOptions(_options); + const result = this.api.v2TasksPersonMergesTaskIdGET(taskId, observableOptions); return result.toPromise(); } @@ -1147,244 +1458,164 @@ export class PromisePersonsApi { } /** - * Paginate through Persons in Affinity. Returns basic information and non-list-specific field data on each Person. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/persons/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Persons will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All People directory\" [permission](#section/Getting-Started/Permissions). - * Get all Persons + * Returns metadata on non-list-specific Person Fields. Use the returned Field IDs to request field data from the GET `/v2/persons` and GET `/v2/persons/{id}` endpoints. + * Get metadata on Person Fields * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page - * @param [ids] People IDs - * @param [fieldIds] Field IDs for which to return field data - * @param [fieldTypes] Field Types for which to return field data */ - public getV2PersonsWithHttpInfo(cursor?: string, limit?: number, ids?: Array, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: PromiseConfigurationOptions): Promise> { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } - const result = this.api.getV2PersonsWithHttpInfo(cursor, limit, ids, fieldIds, fieldTypes, observableOptions); + public v2PersonsFieldsGETWithHttpInfo(cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise> { + const observableOptions = wrapOptions(_options); + const result = this.api.v2PersonsFieldsGETWithHttpInfo(cursor, limit, observableOptions); return result.toPromise(); } /** - * Paginate through Persons in Affinity. Returns basic information and non-list-specific field data on each Person. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/persons/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Persons will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All People directory\" [permission](#section/Getting-Started/Permissions). - * Get all Persons + * Returns metadata on non-list-specific Person Fields. Use the returned Field IDs to request field data from the GET `/v2/persons` and GET `/v2/persons/{id}` endpoints. + * Get metadata on Person Fields * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page - * @param [ids] People IDs - * @param [fieldIds] Field IDs for which to return field data - * @param [fieldTypes] Field Types for which to return field data */ - public getV2Persons(cursor?: string, limit?: number, ids?: Array, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: PromiseConfigurationOptions): Promise { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } - const result = this.api.getV2Persons(cursor, limit, ids, fieldIds, fieldTypes, observableOptions); + public v2PersonsFieldsGET(cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise { + const observableOptions = wrapOptions(_options); + const result = this.api.v2PersonsFieldsGET(cursor, limit, observableOptions); return result.toPromise(); } /** - * Returns metadata on non-list-specific Person Fields. Use the returned Field IDs to request field data from the GET `/v2/persons` and GET `/v2/persons/{id}` endpoints. - * Get metadata on Person Fields + * Paginate through Persons in Affinity. Returns basic information and non-list-specific field data on each Person. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/persons/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Persons will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All People directory\" [permission](#section/Getting-Started/Permissions). + * Get all Persons * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page + * @param [ids] People IDs + * @param [fieldIds] Field IDs for which to return field data + * @param [fieldTypes] Field Types for which to return field data */ - public getV2PersonsFieldsWithHttpInfo(cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise> { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } - const result = this.api.getV2PersonsFieldsWithHttpInfo(cursor, limit, observableOptions); + public v2PersonsGETWithHttpInfo(cursor?: string, limit?: number, ids?: Array, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: PromiseConfigurationOptions): Promise> { + const observableOptions = wrapOptions(_options); + const result = this.api.v2PersonsGETWithHttpInfo(cursor, limit, ids, fieldIds, fieldTypes, observableOptions); return result.toPromise(); } /** - * Returns metadata on non-list-specific Person Fields. Use the returned Field IDs to request field data from the GET `/v2/persons` and GET `/v2/persons/{id}` endpoints. - * Get metadata on Person Fields + * Paginate through Persons in Affinity. Returns basic information and non-list-specific field data on each Person. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/persons/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Persons will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All People directory\" [permission](#section/Getting-Started/Permissions). + * Get all Persons * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page + * @param [ids] People IDs + * @param [fieldIds] Field IDs for which to return field data + * @param [fieldTypes] Field Types for which to return field data */ - public getV2PersonsFields(cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } - const result = this.api.getV2PersonsFields(cursor, limit, observableOptions); + public v2PersonsGET(cursor?: string, limit?: number, ids?: Array, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: PromiseConfigurationOptions): Promise { + const observableOptions = wrapOptions(_options); + const result = this.api.v2PersonsGET(cursor, limit, ids, fieldIds, fieldTypes, observableOptions); return result.toPromise(); } /** * Returns basic information and non-list-specific field data on the requested Person. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/persons/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Persons will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All People directory\" [permission](#section/Getting-Started/Permissions). * Get a single Person - * @param id Person ID + * @param personId Person ID * @param [fieldIds] Field IDs for which to return field data * @param [fieldTypes] Field Types for which to return field data */ - public getV2PersonsIdWithHttpInfo(id: number, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: PromiseConfigurationOptions): Promise> { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } - const result = this.api.getV2PersonsIdWithHttpInfo(id, fieldIds, fieldTypes, observableOptions); + public v2PersonsPersonIdGETWithHttpInfo(personId: number, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: PromiseConfigurationOptions): Promise> { + const observableOptions = wrapOptions(_options); + const result = this.api.v2PersonsPersonIdGETWithHttpInfo(personId, fieldIds, fieldTypes, observableOptions); return result.toPromise(); } /** * Returns basic information and non-list-specific field data on the requested Person. To retrieve field data, you must use either the `fieldIds` or the `fieldTypes` parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET `/v2/persons/fields` endpoint. When no `fieldIds` or `fieldTypes` are provided, Persons will be returned without any field data attached. To supply multiple `fieldIds` or `fieldTypes` parameters, generate a query string that looks like this: `?fieldIds=field-1234&fieldIds=affinity-data-location` or `?fieldTypes=enriched&fieldTypes=global`. Requires the \"Export All People directory\" [permission](#section/Getting-Started/Permissions). * Get a single Person - * @param id Person ID + * @param personId Person ID * @param [fieldIds] Field IDs for which to return field data * @param [fieldTypes] Field Types for which to return field data */ - public getV2PersonsId(id: number, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: PromiseConfigurationOptions): Promise { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } - const result = this.api.getV2PersonsId(id, fieldIds, fieldTypes, observableOptions); + public v2PersonsPersonIdGET(personId: number, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: PromiseConfigurationOptions): Promise { + const observableOptions = wrapOptions(_options); + const result = this.api.v2PersonsPersonIdGET(personId, fieldIds, fieldTypes, observableOptions); return result.toPromise(); } /** * Paginate through the List Entries (AKA rows) for the given Person across all Lists. Each List Entry includes field data for the Person, including list-specific field data. Each List Entry also includes metadata about its creation, i.e., when it was added to the List and by whom. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). * Get a Person\'s List Entries - * @param id Persons ID + * @param personId Persons ID * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page */ - public getV2PersonsIdListEntriesWithHttpInfo(id: number, cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise> { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } - const result = this.api.getV2PersonsIdListEntriesWithHttpInfo(id, cursor, limit, observableOptions); + public v2PersonsPersonIdListEntriesGETWithHttpInfo(personId: number, cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise> { + const observableOptions = wrapOptions(_options); + const result = this.api.v2PersonsPersonIdListEntriesGETWithHttpInfo(personId, cursor, limit, observableOptions); return result.toPromise(); } /** * Paginate through the List Entries (AKA rows) for the given Person across all Lists. Each List Entry includes field data for the Person, including list-specific field data. Each List Entry also includes metadata about its creation, i.e., when it was added to the List and by whom. Requires the \"Export data from Lists\" [permission](#section/Getting-Started/Permissions). * Get a Person\'s List Entries - * @param id Persons ID + * @param personId Persons ID * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page */ - public getV2PersonsIdListEntries(id: number, cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } - const result = this.api.getV2PersonsIdListEntries(id, cursor, limit, observableOptions); + public v2PersonsPersonIdListEntriesGET(personId: number, cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise { + const observableOptions = wrapOptions(_options); + const result = this.api.v2PersonsPersonIdListEntriesGET(personId, cursor, limit, observableOptions); return result.toPromise(); } /** - * Returns metadata for all the Lists on which the given Person appears. + * Paginate through all Lists where the given Person appears as an entry and that you have access to view. Returns basic List information for each List that contains this Person. * Get a Person\'s Lists - * @param id Persons ID + * @param personId Persons ID * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page */ - public getV2PersonsIdListsWithHttpInfo(id: number, cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise> { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } - const result = this.api.getV2PersonsIdListsWithHttpInfo(id, cursor, limit, observableOptions); + public v2PersonsPersonIdListsGETWithHttpInfo(personId: number, cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise> { + const observableOptions = wrapOptions(_options); + const result = this.api.v2PersonsPersonIdListsGETWithHttpInfo(personId, cursor, limit, observableOptions); return result.toPromise(); } /** - * Returns metadata for all the Lists on which the given Person appears. + * Paginate through all Lists where the given Person appears as an entry and that you have access to view. Returns basic List information for each List that contains this Person. * Get a Person\'s Lists - * @param id Persons ID + * @param personId Persons ID + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + */ + public v2PersonsPersonIdListsGET(personId: number, cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise { + const observableOptions = wrapOptions(_options); + const result = this.api.v2PersonsPersonIdListsGET(personId, cursor, limit, observableOptions); + return result.toPromise(); + } + + /** + * | ⚠️ This endpoint is currently in BETA | |--| Returns notes for a given person id which includes directly attached notes, notes on meetings this person attended, and notes where this person is mentioned. You can filter notes using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|---------------------------------| | `creator.id` | Filter notes by the creator of the note | `int32` | `=` | `creator.id=1` | | `createdAt` | Filter notes by when it was created | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-02-04T10:48:24Z` | | `updatedAt` | Filter notes by when it was updated | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-02-03T10:48:24Z`| + * Get Notes for a Person + * @param personId Persons ID + * @param [filter] Filter options + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + * @param [totalCount] Include total count of the collection in the pagination response + */ + public v2PersonsPersonIdNotesGETWithHttpInfo(personId: number, filter?: string, cursor?: string, limit?: number, totalCount?: boolean, _options?: PromiseConfigurationOptions): Promise> { + const observableOptions = wrapOptions(_options); + const result = this.api.v2PersonsPersonIdNotesGETWithHttpInfo(personId, filter, cursor, limit, totalCount, observableOptions); + return result.toPromise(); + } + + /** + * | ⚠️ This endpoint is currently in BETA | |--| Returns notes for a given person id which includes directly attached notes, notes on meetings this person attended, and notes where this person is mentioned. You can filter notes using the `filter` query parameter. The filter parameter is a string that you can specify conditions based on the following properties. | **Property Name** | **Description** | **Type** | **Allowed Operators** | **Examples** | |-----------------------------|-----------------------------------------------------------------|------------|--------------------------------------|---------------------------------| | `creator.id` | Filter notes by the creator of the note | `int32` | `=` | `creator.id=1` | | `createdAt` | Filter notes by when it was created | `datetime` | `>`, `<`, `>=`, `<=` | `createdAt<2025-02-04T10:48:24Z` | | `updatedAt` | Filter notes by when it was updated | `datetime` | `>`, `<`, `>=`, `<=` | `updatedAt>=2025-02-03T10:48:24Z`| + * Get Notes for a Person + * @param personId Persons ID + * @param [filter] Filter options * @param [cursor] Cursor for the next or previous page * @param [limit] Number of items to include in the page + * @param [totalCount] Include total count of the collection in the pagination response */ - public getV2PersonsIdLists(id: number, cursor?: string, limit?: number, _options?: PromiseConfigurationOptions): Promise { - let observableOptions: undefined | ConfigurationOptions - if (_options){ - observableOptions = { - baseServer: _options.baseServer, - httpApi: _options.httpApi, - middleware: _options.middleware?.map( - m => new PromiseMiddlewareWrapper(m) - ), - middlewareMergeStrategy: _options.middlewareMergeStrategy, - authMethods: _options.authMethods - } - } - const result = this.api.getV2PersonsIdLists(id, cursor, limit, observableOptions); + public v2PersonsPersonIdNotesGET(personId: number, filter?: string, cursor?: string, limit?: number, totalCount?: boolean, _options?: PromiseConfigurationOptions): Promise { + const observableOptions = wrapOptions(_options); + const result = this.api.v2PersonsPersonIdNotesGET(personId, filter, cursor, limit, totalCount, observableOptions); return result.toPromise(); } diff --git a/src/v2/tests/smoke_test.ts b/src/v2/tests/smoke_test.ts index 2de95ce..9ce6dc3 100644 --- a/src/v2/tests/smoke_test.ts +++ b/src/v2/tests/smoke_test.ts @@ -52,7 +52,7 @@ describe('V2', () => { } const authApi = new AuthApi(config) - const auth = await authApi.getV2AuthWhoami() + const auth = await authApi.v2AuthWhoamiGET() await assertSnapshot(t, auth) }) @@ -99,7 +99,7 @@ describe('V2', () => { for await ( const page of paginated( - companiesApi.getV2Companies.bind(companiesApi), + companiesApi.v2CompaniesGET.bind(companiesApi), )({ limit: 1, })