From 8fc8221a2921dfd08f9d0a15902edc7782754e99 Mon Sep 17 00:00:00 2001 From: Joscha Feth Date: Thu, 26 Sep 2024 09:50:07 +0100 Subject: [PATCH 1/9] chore: update OpenAPI spec --- openapi/{2024-09-05.json => 2024-09-26.json} | 4548 +++++++++--------- 1 file changed, 2308 insertions(+), 2240 deletions(-) rename openapi/{2024-09-05.json => 2024-09-26.json} (70%) diff --git a/openapi/2024-09-05.json b/openapi/2024-09-26.json similarity index 70% rename from openapi/2024-09-05.json rename to openapi/2024-09-26.json index 70b2c29..cdd1c53 100644 --- a/openapi/2024-09-05.json +++ b/openapi/2024-09-26.json @@ -1,12 +1,12 @@ { - "openapi": "3.0.1", + "openapi": "3.1.0", "info": { "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 data,\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 multiple\n List Entries on the same List. These List Entries can have different list-specific field data\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 API,\n their data can only be accessed through the List Entry resource. \"Global\" data from other Fields\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 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\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## 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\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", + "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## 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\",\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\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\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", "termsOfService": "https://www.affinity.co/legal/terms-of-use", "title": "Affinity API v2", "version": "2.0.0", @@ -1642,1339 +1642,553 @@ } }, "components": { + "securitySchemes": { + "bearerAuth": { + "type": "http", + "scheme": "bearer" + } + }, "schemas": { - "ListWithTypePaged": { - "description": "ListWithTypePaged model", - "example": { - "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, - "type": "company" - }, - { - "name": "All companies", - "creatorId": 1, - "isPublic": false, - "id": 1, - "ownerId": 1, - "type": "company" - } - ] - }, - "properties": { - "data": { - "description": "A page of ListWithType results", - "items": { - "$ref": "#/components/schemas/ListWithType" - }, - "type": "array" - }, - "pagination": { - "$ref": "#/components/schemas/Pagination" + "Tenant": { + "examples": [ + { + "name": "Contoso Ltd.", + "subdomain": "contoso", + "id": 1 } - }, - "required": [ - "data", - "pagination" ], - "type": "object" - }, - "ListWithType": { - "description": "ListWithType model", - "example": { - "name": "All companies", - "creatorId": 1, - "isPublic": false, - "id": 1, - "ownerId": 1, - "type": "company" - }, "properties": { "id": { - "description": "The unique identifier for the list", - "example": 1, + "description": "The tenant's unique identifier", + "examples": [ + 1 + ], "format": "int64", "type": "integer" }, "name": { - "description": "The name of the list", - "example": "All companies", + "description": "The name of the tenant", + "examples": [ + "Contoso Ltd." + ], "type": "string" }, - "creatorId": { - "description": "The ID of the user that created this list", - "example": 1, - "format": "int64", - "type": "integer" - }, - "ownerId": { - "description": "The ID of the user that owns this list", - "example": 1, - "format": "int64", - "type": "integer" - }, - "isPublic": { - "description": "Whether or not the list is public", - "example": false, - "type": "boolean" - }, - "type": { - "description": "The entity type for this list", - "enum": [ - "company", - "opportunity", - "person" + "subdomain": { + "description": "The tenant's subdomain under affinity.co", + "examples": [ + "contoso" ], - "example": "company", + "format": "hostname", "type": "string" } }, "required": [ - "creatorId", "id", - "isPublic", "name", - "ownerId", - "type" + "subdomain" ], "type": "object" }, - "Pagination": { - "example": { - "prevUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgYmVmb3JlOjo6Nw", - "nextUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgIGFmdGVyOjo6NA" - }, - "properties": { - "prevUrl": { - "description": "URL for the previous page", - "example": "https://api.affinity.co/v2/foo?cursor=ICAgICAgYmVmb3JlOjo6Nw", - "format": "url", - "type": "string", - "nullable": true - }, - "nextUrl": { - "description": "URL for the next page", - "example": "https://api.affinity.co/v2/foo?cursor=ICAgICAgIGFmdGVyOjo6NA", - "format": "url", - "type": "string", - "nullable": true - } - }, - "type": "object" - }, - "PersonPaged": { - "description": "PersonPaged model", - "example": { - "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" - } - ] - }, - "properties": { - "data": { - "description": "A page of Person results", - "items": { - "$ref": "#/components/schemas/Person" - }, - "type": "array" - }, - "pagination": { - "$ref": "#/components/schemas/Pagination" + "User": { + "examples": [ + { + "firstName": "John", + "lastName": "Smith", + "emailAddress": "john.smith@contoso.com", + "id": 1 } - }, - "required": [ - "data", - "pagination" ], - "type": "object" - }, - "Person": { - "description": "Person model", - "example": { - "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" - }, "properties": { "id": { - "description": "The persons's unique identifier", - "example": 1, + "description": "The user's unique identifier", + "examples": [ + 1 + ], "format": "int64", "type": "integer" }, "firstName": { - "description": "The person's first name", - "example": "Jane", + "description": "The user's first name", + "examples": [ + "John" + ], "type": "string" }, "lastName": { - "description": "The person's last name", - "example": "Doe", - "type": "string", - "nullable": true - }, - "primaryEmailAddress": { - "description": "The person's primary email address", - "example": "jane.doe@acme.co", - "format": "email", - "type": "string", - "nullable": true - }, - "emailAddresses": { - "description": "All of the person's email addresses", - "example": [ - "jane.doe@acme.co", - "janedoe@gmail.com" + "description": "The user's last name", + "examples": [ + "Smith" ], - "items": { - "format": "email", - "type": "string" - }, - "type": "array" + "type": [ + "string", + "null" + ] }, - "type": { - "description": "The person's type", - "enum": [ - "internal", - "external" + "emailAddress": { + "description": "The user's email address", + "examples": [ + "john.smith@contoso.com" ], - "example": "internal", + "format": "email", "type": "string" - }, - "fields": { - "description": "The fields associated with the person", - "items": { - "$ref": "#/components/schemas/Field" - }, - "type": "array" } }, "required": [ - "emailAddresses", + "emailAddress", "firstName", "id", - "lastName", - "primaryEmailAddress", - "type" + "lastName" ], "type": "object" }, - "Field": { - "example": { - "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" + "Grant": { + "examples": [ + { + "createdAt": "2023-01-01 00:00:00.000000000 Z", + "scopes": [ + "api" + ], + "type": "api-key" } - }, + ], "properties": { - "id": { - "description": "The field's unique identifier", - "example": "affinity-data-location", - "type": "string" - }, - "name": { - "description": "The field's name", - "example": "Location", - "type": "string" - }, "type": { - "description": "The field's type", - "enum": [ - "enriched", - "global", - "list", - "relationship-intelligence" + "description": "The type of grant used to authenticate", + "const": "api-key", + "examples": [ + "api-key" ], - "example": "enriched", "type": "string" }, - "enrichmentSource": { - "description": "The source of the data in this Field (if it is enriched)", - "enum": [ - "affinity-data", - "dealroom", - null + "scopes": { + "description": "The scopes available to the current grant", + "examples": [ + [ + "api" + ] ], - "example": "affinity-data", - "type": "string", - "nullable": true + "items": { + "type": "string" + }, + "type": "array" }, - "value": { - "$ref": "#/components/schemas/FieldValue" + "createdAt": { + "description": "When the grant was created", + "examples": [ + "2023-01-01T00:00:00Z" + ], + "format": "date-time", + "type": "string" } }, "required": [ - "enrichmentSource", - "id", - "name", - "type", - "value" + "createdAt", + "scopes", + "type" ], "type": "object" }, - "FieldValue": { - "example": { - "data": { - "continent": "North America", - "country": "United States", - "streetAddress": "170 Columbus Ave", - "city": "San Francisco", - "state": "California" - }, - "type": "location" - }, + "WhoAmI": { + "description": "WhoAmI model", + "examples": [ + { + "grant": { + "createdAt": "2023-01-01 00:00:00.000000000 Z", + "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 + } + } + ], "properties": { - "type": { - "description": "The type of value", - "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" - ], - "example": "location", - "type": "string" + "tenant": { + "$ref": "#/components/schemas/Tenant" + }, + "user": { + "$ref": "#/components/schemas/User" + }, + "grant": { + "$ref": "#/components/schemas/Grant" } }, "required": [ - "type" + "grant", + "tenant", + "user" ], - "type": "object", - "discriminator": { - "propertyName": "type", - "mapping": { - "person": "#/components/schemas/PersonValue", - "person-multi": "#/components/schemas/PersonsValue", - "company": "#/components/schemas/CompanyValue", - "company-multi": "#/components/schemas/CompaniesValue", - "filterable-text": "#/components/schemas/TextValue", - "filterable-text-multi": "#/components/schemas/TextsValue", - "location": "#/components/schemas/LocationValue", - "location-multi": "#/components/schemas/LocationsValue", - "number": "#/components/schemas/FloatValue", - "number-multi": "#/components/schemas/FloatsValue", - "datetime": "#/components/schemas/DateValue", - "text": "#/components/schemas/TextValue", - "ranked-dropdown": "#/components/schemas/RankedDropdownValue", - "dropdown": "#/components/schemas/DropdownValue", - "dropdown-multi": "#/components/schemas/DropdownsValue", - "formula-number": "#/components/schemas/FormulaValue", - "interaction": "#/components/schemas/InteractionValue" - } - }, - "oneOf": [ - { - "$ref": "#/components/schemas/PersonValue" - }, - { - "$ref": "#/components/schemas/PersonsValue" - }, - { - "$ref": "#/components/schemas/CompanyValue" - }, - { - "$ref": "#/components/schemas/CompaniesValue" - }, - { - "$ref": "#/components/schemas/TextValue" - }, - { - "$ref": "#/components/schemas/TextsValue" - }, - { - "$ref": "#/components/schemas/LocationValue" - }, - { - "$ref": "#/components/schemas/LocationsValue" - }, - { - "$ref": "#/components/schemas/FloatValue" - }, - { - "$ref": "#/components/schemas/FloatsValue" - }, - { - "$ref": "#/components/schemas/DateValue" - }, - { - "$ref": "#/components/schemas/RankedDropdownValue" - }, - { - "$ref": "#/components/schemas/DropdownValue" - }, - { - "$ref": "#/components/schemas/DropdownsValue" - }, - { - "$ref": "#/components/schemas/FormulaValue" - }, + "type": "object" + }, + "AuthenticationError": { + "examples": [ { - "$ref": "#/components/schemas/InteractionValue" + "code": "authentication", + "message": "🚨 Error! Sound the alarm! 🚨" } - ] - }, - "Location": { - "example": { - "continent": "North America", - "country": "United States", - "streetAddress": "170 Columbus Ave", - "city": "San Francisco", - "state": "California" - }, + ], "properties": { - "streetAddress": { - "description": "Street address", - "example": "170 Columbus Ave", - "type": "string", - "nullable": true - }, - "city": { - "description": "City", - "example": "San Francisco", - "type": "string", - "nullable": true - }, - "state": { - "description": "State", - "example": "California", - "type": "string", - "nullable": true - }, - "country": { - "description": "Country", - "example": "United States", - "type": "string", - "nullable": true + "code": { + "description": "Error code", + "const": "authentication", + "type": "string" }, - "continent": { - "description": "Continent", - "example": "North America", - "type": "string", - "nullable": true + "message": { + "description": "Error message", + "type": "string" } }, "required": [ - "city", - "continent", - "country", - "state", - "streetAddress" + "code", + "message" ], "type": "object" }, - "OpportunityPaged": { - "description": "OpportunityPaged model", - "example": { - "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 - } - ] - }, + "AuthenticationErrors": { + "description": "AuthenticationErrors model", + "examples": [ + { + "errors": [ + { + "code": "authentication", + "message": "🚨 Error! Sound the alarm! 🚨" + }, + { + "code": "authentication", + "message": "🚨 Error! Sound the alarm! 🚨" + } + ] + } + ], "properties": { - "data": { - "description": "A page of Opportunity results", + "errors": { + "description": "AuthenticationError errors", "items": { - "$ref": "#/components/schemas/Opportunity" + "$ref": "#/components/schemas/AuthenticationError" }, "type": "array" - }, - "pagination": { - "$ref": "#/components/schemas/Pagination" } }, "required": [ - "data", - "pagination" + "errors" ], "type": "object" }, - "Opportunity": { - "description": "Opportunity model", - "example": { - "listId": 1, - "name": "Acme Upsell $10k", - "id": 1 - }, + "NotFoundError": { + "examples": [ + { + "code": "not-found", + "message": "🚨 Error! Sound the alarm! 🚨" + } + ], "properties": { - "id": { - "description": "The unique identifier for the opportunity", - "example": 1, - "format": "int64", - "type": "integer" - }, - "name": { - "description": "The name of the opportunity", - "example": "Acme Upsell $10k", + "code": { + "description": "Error code", + "const": "not-found", "type": "string" }, - "listId": { - "description": "The ID of the list that the opportunity belongs to", - "example": 1, - "format": "int64", - "type": "integer" - } - }, - "required": [ - "id", - "listId", - "name" - ], - "type": "object" - }, - "ListEntryWithEntityPaged": { - "description": "ListEntryWithEntityPaged model", - "example": { - "pagination": { - "prevUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgYmVmb3JlOjo6Nw", - "nextUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgIGFmdGVyOjo6NA" - }, - "data": [ - { - "createdAt": "2023-01-01 00:00:00.000000000 Z", - "creatorId": 1, - "id": 1, - "type": "company", - "entity": { - "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" - } - } - ] - } - }, - { - "createdAt": "2023-01-01 00:00:00.000000000 Z", - "creatorId": 1, - "id": 1, - "type": "company", - "entity": { - "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" - } - } - ] - } - } - ] - }, - "properties": { - "data": { - "description": "A page of ListEntryWithEntity results", - "items": { - "$ref": "#/components/schemas/ListEntryWithEntity" - }, - "type": "array", - "nullable": true - }, - "pagination": { - "$ref": "#/components/schemas/Pagination" + "message": { + "description": "Error message", + "type": "string" } }, "required": [ - "data", - "pagination" + "code", + "message" ], "type": "object" }, - "ListEntryWithEntity": { - "example": { - "createdAt": "2023-01-01 00:00:00.000000000 Z", - "creatorId": 1, - "id": 1, - "type": "company", - "entity": { - "domain": "acme.co", - "name": "Acme", - "isGlobal": true, - "domains": [ - "acme.co" - ], - "id": 1, - "fields": [ + "NotFoundErrors": { + "description": "NotFoundErrors model", + "examples": [ + { + "errors": [ { - "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": "not-found", + "message": "🚨 Error! Sound the alarm! 🚨" }, { - "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": "not-found", + "message": "🚨 Error! Sound the alarm! 🚨" } ] } - }, + ], "properties": { - "type": { - "description": "The entity type for this list entry", - "enum": [ - "company", - "opportunity", - "person" - ], - "example": "company", - "type": "string" + "errors": { + "description": "NotFoundError errors", + "items": { + "$ref": "#/components/schemas/NotFoundError" + }, + "type": "array" } }, "required": [ - "type" + "errors" ], - "type": "object", - "discriminator": { - "propertyName": "type", - "mapping": { - "company": "#/components/schemas/CompanyListEntry", - "opportunity": "#/components/schemas/OpportunityListEntry", - "person": "#/components/schemas/PersonListEntry" - } - }, - "oneOf": [ - { - "$ref": "#/components/schemas/CompanyListEntry" - }, - { - "$ref": "#/components/schemas/OpportunityListEntry" - }, - { - "$ref": "#/components/schemas/PersonListEntry" - } - ] + "type": "object" }, - "Company": { - "description": "Company model", - "example": { - "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" - } - } - ] - }, + "CompanyData": { "properties": { "id": { "description": "The company's unique identifier", - "example": 1, + "examples": [ + 1 + ], "format": "int64", "type": "integer" }, "name": { "description": "The company's name", - "example": "Acme", + "examples": [ + "Acme" + ], "type": "string" }, "domain": { "description": "The company's primary domain", - "example": "acme.co", - "format": "hostname", - "type": "string" - }, - "domains": { - "description": "All of the company's domains", - "example": [ + "examples": [ "acme.co" ], - "items": { - "format": "hostname", - "type": "string" - }, - "type": "array" - }, - "isGlobal": { - "description": "Whether or not the company is org specific", - "example": true, - "type": "boolean" - }, - "fields": { - "description": "The fields associated with the company", - "items": { - "$ref": "#/components/schemas/Field" - }, - "type": "array" + "format": "hostname", + "type": "string" } }, "required": [ "domain", - "domains", "id", - "isGlobal", "name" ], "type": "object" }, - "SavedViewPaged": { - "description": "SavedViewPaged model", - "example": { - "pagination": { - "prevUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgYmVmb3JlOjo6Nw", - "nextUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgIGFmdGVyOjo6NA" - }, - "data": [ - { - "createdAt": "2023-01-01 00:00:00.000000000 Z", - "name": "my interesting companies", - "id": 28, - "type": "sheet" - }, - { - "createdAt": "2023-01-01 00:00:00.000000000 Z", - "name": "my interesting companies", - "id": 28, - "type": "sheet" - } - ] - }, + "CompaniesValue": { + "title": "CompaniesValue", "properties": { - "data": { - "description": "A page of SavedView results", + "type": { + "description": "The type of value", + "const": "company-multi", + "type": "string" + }, + "data": { + "description": "The values for many companies", "items": { - "$ref": "#/components/schemas/SavedView" + "$ref": "#/components/schemas/CompanyData" }, - "type": "array" - }, - "pagination": { - "$ref": "#/components/schemas/Pagination" + "type": [ + "array", + "null" + ] } }, "required": [ "data", - "pagination" + "type" ], "type": "object" }, - "SavedView": { - "description": "SavedView model", - "example": { - "createdAt": "2023-01-01 00:00:00.000000000 Z", - "name": "my interesting companies", - "id": 28, - "type": "sheet" - }, + "CompanyValue": { + "title": "CompanyValue", "properties": { - "id": { - "description": "The saved view's unique identifier", - "example": 28, - "format": "int64", - "type": "integer" - }, - "name": { - "description": "The saved view's name", - "example": "my interesting companies", + "type": { + "description": "The type of value", + "const": "company", "type": "string" }, + "data": { + "oneOf": [ + { + "$ref": "#/components/schemas/CompanyData" + }, + { + "type": "null" + } + ] + } + }, + "required": [ + "data", + "type" + ], + "type": "object" + }, + "DateValue": { + "title": "DateValue", + "properties": { "type": { - "description": "The type for this saved view", - "enum": [ - "sheet", - "board", - "dashboard" - ], - "example": "sheet", + "description": "The type of value", + "const": "datetime", "type": "string" }, - "createdAt": { - "description": "The date that the saved view was created", - "example": "2023-01-01 00:00:00.000000000 Z", + "data": { + "description": "The value for a date", "format": "date-time", - "type": "string" + "type": [ + "string", + "null" + ] } }, "required": [ - "createdAt", - "id", - "name", + "data", "type" ], "type": "object" }, - "CompanyPaged": { - "description": "CompanyPaged model", - "example": { - "pagination": { - "prevUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgYmVmb3JlOjo6Nw", - "nextUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgIGFmdGVyOjo6NA" + "Dropdown": { + "properties": { + "dropdownOptionId": { + "description": "Dropdown item's unique identifier", + "examples": [ + 1 + ], + "format": "int64", + "type": "integer" }, - "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" - } - } - ] - } - ] + "text": { + "description": "Dropdown item text", + "examples": [ + "first" + ], + "type": "string" + } }, + "required": [ + "dropdownOptionId", + "text" + ], + "type": "object" + }, + "DropdownValue": { + "title": "DropdownValue", "properties": { - "data": { - "description": "A page of Company results", - "items": { - "$ref": "#/components/schemas/Company" - }, - "type": "array" + "type": { + "description": "The type of value", + "const": "dropdown", + "type": "string" }, - "pagination": { - "$ref": "#/components/schemas/Pagination" + "data": { + "oneOf": [ + { + "$ref": "#/components/schemas/Dropdown" + }, + { + "type": "null" + } + ] } }, "required": [ "data", - "pagination" + "type" ], "type": "object" }, - "FieldMetadataPaged": { - "description": "FieldMetadataPaged model", - "example": { - "pagination": { - "prevUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgYmVmb3JlOjo6Nw", - "nextUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgIGFmdGVyOjo6NA" - }, - "data": [ - { - "enrichmentSource": "affinity-data", - "valueType": "location", - "name": "Location", - "id": "affinity-data-location", - "type": "enriched" - }, - { - "enrichmentSource": "affinity-data", - "valueType": "location", - "name": "Location", - "id": "affinity-data-location", - "type": "enriched" - } - ] - }, + "DropdownsValue": { + "title": "DropdownsValue", "properties": { + "type": { + "description": "The type of value", + "const": "dropdown-multi", + "type": "string" + }, "data": { - "description": "A page of FieldMetadata results", + "description": "The value for many dropdown items", "items": { - "$ref": "#/components/schemas/FieldMetadata" + "$ref": "#/components/schemas/Dropdown" }, - "type": "array" - }, - "pagination": { - "$ref": "#/components/schemas/Pagination" + "type": [ + "array", + "null" + ] } }, "required": [ "data", - "pagination" + "type" ], "type": "object" }, - "FieldMetadata": { - "example": { - "enrichmentSource": "affinity-data", - "valueType": "location", - "name": "Location", - "id": "affinity-data-location", - "type": "enriched" - }, + "FloatValue": { + "title": "FloatValue", "properties": { - "id": { - "description": "The field's unique identifier", - "example": "affinity-data-location", - "type": "string" - }, - "name": { - "description": "The field's name", - "example": "Location", + "type": { + "description": "The type of value", + "const": "number", "type": "string" }, + "data": { + "description": "The value for a number", + "type": [ + "number", + "null" + ] + } + }, + "required": [ + "data", + "type" + ], + "type": "object" + }, + "FloatsValue": { + "title": "FloatsValue", + "properties": { "type": { - "description": "The field's type", - "enum": [ - "enriched", - "global", - "list", - "relationship-intelligence" - ], - "example": "enriched", + "description": "The type of value", + "const": "number-multi", "type": "string" }, - "enrichmentSource": { - "description": "The source of the data in this Field (if it is enriched)", - "enum": [ - "affinity-data", - "dealroom", - null - ], - "example": "affinity-data", - "type": "string", - "nullable": true - }, - "valueType": { - "description": "The type of the data in this Field", - "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" - ], - "example": "location", - "type": "string" + "data": { + "description": "The value for many numbers", + "items": { + "type": "number" + }, + "type": [ + "array", + "null" + ] } }, "required": [ - "enrichmentSource", - "id", - "name", - "type", - "valueType" + "data", + "type" ], "type": "object" }, - "PhoneCall": { + "FormulaNumber": { "properties": { - "type": { - "description": "The type of interaction", - "enum": [ - "call" - ], - "example": "call", - "type": "string" - }, - "id": { - "description": "The phon_call's unique identifier", - "example": 1, - "format": "int64", - "type": "integer" - }, - "startTime": { - "description": "The call start time", - "example": "2023-02-03 04:00:00.000000000 Z", - "format": "date-time", - "type": "string" - }, - "attendees": { - "description": "People attending the call", - "example": [ - "Affinity::ExternalAPIV2::Examples::Attendee" - ], - "items": { - "$ref": "#/components/schemas/Attendee" - }, - "type": "array" + "calculatedValue": { + "description": "Calculated value", + "type": [ + "number", + "null" + ] } }, - "required": [ - "attendees", - "id", - "startTime", - "type" - ], "type": "object" }, - "Attendee": { + "FormulaValue": { + "title": "FormulaValue", "properties": { - "emailAddress": { - "description": "The email addresses of the attendee", - "example": "john.smith@contoso.com", - "format": "email", - "type": "string", - "nullable": true + "type": { + "description": "The type of value", + "const": "formula-number", + "type": "string" }, - "person": { + "data": { "oneOf": [ { - "$ref": "#/components/schemas/PersonData" + "$ref": "#/components/schemas/FormulaNumber" }, { "type": "null" @@ -2983,8 +2197,8 @@ } }, "required": [ - "emailAddress", - "person" + "data", + "type" ], "type": "object" }, @@ -2992,28 +2206,42 @@ "properties": { "id": { "description": "The persons's unique identifier", - "example": 1, + "examples": [ + 1 + ], "format": "int64", "type": "integer" }, "firstName": { "description": "The person's first name", - "example": "Jane", - "type": "string", - "nullable": true + "examples": [ + "Jane" + ], + "type": [ + "string", + "null" + ] }, "lastName": { "description": "The person's last name", - "example": "Doe", - "type": "string", - "nullable": true + "examples": [ + "Doe" + ], + "type": [ + "string", + "null" + ] }, "primaryEmailAddress": { "description": "The person's primary email address", - "example": "jane.doe@acme.co", + "examples": [ + "jane.doe@acme.co" + ], "format": "email", - "type": "string", - "nullable": true + "type": [ + "string", + "null" + ] }, "type": { "description": "The person's type", @@ -3022,7 +2250,9 @@ "external", "collaborator" ], - "example": "internal", + "examples": [ + "internal" + ], "type": "string" } }, @@ -3035,93 +2265,127 @@ ], "type": "object" }, - "Meeting": { + "ChatMessage": { "properties": { "type": { "description": "The type of interaction", - "enum": [ - "meeting" + "const": "chat-message", + "examples": [ + "chat-message" ], - "example": "meeting", "type": "string" }, "id": { - "description": "The meeting's unique identifier", - "example": 1, + "description": "The chat message's unique identifier", + "examples": [ + 1 + ], "format": "int64", "type": "integer" }, - "title": { - "description": "The meeting's title", - "example": "Acme Upsell $10k", - "type": "string", - "nullable": true - }, - "allDay": { - "description": "Whether the meeting is an all-day event", - "example": false, - "type": "boolean" + "direction": { + "description": "The direction of the chat message", + "enum": [ + "received", + "sent" + ], + "examples": [ + "outbound" + ], + "type": "string" }, - "startTime": { - "description": "The meeting start time", - "example": "2023-02-03 04:00:00.000000000 Z", + "sentAt": { + "description": "The time the chat message was sent", + "examples": [ + "2023-01-01T00:00:00Z" + ], "format": "date-time", "type": "string" }, - "endTime": { - "description": "The meeting end time", - "example": "2023-02-03 05:00:00.000000000 Z", - "format": "date-time", - "type": "string", - "nullable": true + "manualCreator": { + "$ref": "#/components/schemas/PersonData" }, - "attendees": { - "description": "People attending the meeting", - "example": [ - "Affinity::ExternalAPIV2::Examples::Attendee" - ], + "participants": { + "description": "The participants of the chat", "items": { - "$ref": "#/components/schemas/Attendee" + "$ref": "#/components/schemas/PersonData" }, "type": "array" } }, "required": [ - "allDay", - "attendees", - "endTime", + "direction", "id", - "startTime", - "title", + "manualCreator", + "participants", + "sentAt", "type" ], "type": "object" }, + "Attendee": { + "properties": { + "emailAddress": { + "description": "The email addresses of the attendee", + "examples": [ + "john.smith@contoso.com" + ], + "format": "email", + "type": [ + "string", + "null" + ] + }, + "person": { + "oneOf": [ + { + "$ref": "#/components/schemas/PersonData" + }, + { + "type": "null" + } + ] + } + }, + "required": [ + "emailAddress", + "person" + ], + "type": "object" + }, "Email": { "properties": { "type": { "description": "The type of interaction", - "enum": [ + "const": "email", + "examples": [ "email" ], - "example": "email", "type": "string" }, "id": { "description": "The email's unique identifier", - "example": 1, + "examples": [ + 1 + ], "format": "int64", "type": "integer" }, "subject": { "description": "The subject of the email", - "example": "Acme Upsell $10k", - "type": "string", - "nullable": true + "examples": [ + "Acme Upsell $10k" + ], + "type": [ + "string", + "null" + ] }, "sentAt": { "description": "The time the email was sent", - "example": "2023-01-01 00:00:00.000000000 Z", + "examples": [ + "2023-01-01T00:00:00Z" + ], "format": "date-time", "type": "string" }, @@ -3130,9 +2394,6 @@ }, "to": { "description": "The recipients of the email", - "example": [ - "Affinity::ExternalAPIV2::Examples::Attendee" - ], "items": { "$ref": "#/components/schemas/Attendee" }, @@ -3140,9 +2401,6 @@ }, "cc": { "description": "The cc recipients of the email", - "example": [ - "Affinity::ExternalAPIV2::Examples::Attendee" - ], "items": { "$ref": "#/components/schemas/Attendee" }, @@ -3160,91 +2418,153 @@ ], "type": "object" }, - "ChatMessage": { + "Meeting": { "properties": { "type": { "description": "The type of interaction", - "enum": [ - "chat-message" + "const": "meeting", + "examples": [ + "meeting" ], - "example": "chat-message", "type": "string" }, "id": { - "description": "The chat message's unique identifier", - "example": 1, + "description": "The meeting's unique identifier", + "examples": [ + 1 + ], "format": "int64", "type": "integer" }, - "direction": { - "description": "The direction of the chat message", - "enum": [ - "received", - "sent" + "title": { + "description": "The meeting's title", + "examples": [ + "Acme Upsell $10k" ], - "example": "outbound", - "type": "string" + "type": [ + "string", + "null" + ] }, - "sentAt": { - "description": "The time the chat message was sent", - "example": "2023-01-01 00:00:00.000000000 Z", + "allDay": { + "description": "Whether the meeting is an all-day event", + "examples": [ + false + ], + "type": "boolean" + }, + "startTime": { + "description": "The meeting start time", + "examples": [ + "2023-02-03T04:00:00Z" + ], "format": "date-time", "type": "string" }, - "manualCreator": { - "$ref": "#/components/schemas/PersonData" - }, - "participants": { - "description": "The participants of the chat", - "example": [ - "Affinity::ExternalAPIV2::Examples::Person" + "endTime": { + "description": "The meeting end time", + "examples": [ + "2023-02-03T05:00:00Z" ], + "format": "date-time", + "type": [ + "string", + "null" + ] + }, + "attendees": { + "description": "People attending the meeting", "items": { - "$ref": "#/components/schemas/PersonData" + "$ref": "#/components/schemas/Attendee" }, "type": "array" } }, "required": [ - "direction", + "allDay", + "attendees", + "endTime", "id", - "manualCreator", - "participants", - "sentAt", + "startTime", + "title", "type" ], "type": "object" }, - "Interaction": { + "PhoneCall": { "properties": { "type": { "description": "The type of interaction", - "enum": [ - "call", - "email", - "meeting", - "chat-message" + "const": "call", + "examples": [ + "call" ], - "example": "meeting", "type": "string" - } - }, - "required": [ - "type" - ], - "type": "object", - "discriminator": { - "propertyName": "type", - "mapping": { - "chat-message": "#/components/schemas/ChatMessage", - "email": "#/components/schemas/Email", - "meeting": "#/components/schemas/Meeting", - "call": "#/components/schemas/PhoneCall" - } - }, - "oneOf": [ - { - "$ref": "#/components/schemas/ChatMessage" + }, + "id": { + "description": "The phon_call's unique identifier", + "examples": [ + 1 + ], + "format": "int64", + "type": "integer" + }, + "startTime": { + "description": "The call start time", + "examples": [ + "2023-02-03T04:00:00Z" + ], + "format": "date-time", + "type": "string" + }, + "attendees": { + "description": "People attending the call", + "items": { + "$ref": "#/components/schemas/Attendee" + }, + "type": "array" + } + }, + "required": [ + "attendees", + "id", + "startTime", + "type" + ], + "type": "object" + }, + "Interaction": { + "properties": { + "type": { + "description": "The type of interaction", + "enum": [ + "call", + "email", + "meeting", + "chat-message" + ], + "examples": [ + "meeting" + ], + "type": "string" + } + }, + "required": [ + "type" + ], + "type": "object", + "discriminator": { + "propertyName": "type", + "mapping": { + "chat-message": "#/components/schemas/ChatMessage", + "email": "#/components/schemas/Email", + "meeting": "#/components/schemas/Meeting", + "call": "#/components/schemas/PhoneCall" + } + }, + "oneOf": [ + { + "$ref": "#/components/schemas/ChatMessage" }, { "$ref": "#/components/schemas/Email" @@ -3258,12 +2578,11 @@ ] }, "InteractionValue": { + "title": "InteractionValue", "properties": { "type": { "description": "The type of value", - "enum": [ - "interaction" - ], + "const": "interaction", "type": "string" }, "data": { @@ -3283,29 +2602,89 @@ ], "type": "object" }, - "FormulaNumber": { + "Location": { + "examples": [ + { + "continent": "North America", + "country": "United States", + "streetAddress": "170 Columbus Ave", + "city": "San Francisco", + "state": "California" + } + ], "properties": { - "calculatedValue": { - "description": "Calculated value", - "type": "number", - "nullable": true + "streetAddress": { + "description": "Street address", + "examples": [ + "170 Columbus Ave" + ], + "type": [ + "string", + "null" + ] + }, + "city": { + "description": "City", + "examples": [ + "San Francisco" + ], + "type": [ + "string", + "null" + ] + }, + "state": { + "description": "State", + "examples": [ + "California" + ], + "type": [ + "string", + "null" + ] + }, + "country": { + "description": "Country", + "examples": [ + "United States" + ], + "type": [ + "string", + "null" + ] + }, + "continent": { + "description": "Continent", + "examples": [ + "North America" + ], + "type": [ + "string", + "null" + ] } }, + "required": [ + "city", + "continent", + "country", + "state", + "streetAddress" + ], "type": "object" }, - "FormulaValue": { + "LocationValue": { + "title": "LocationValue", "properties": { "type": { "description": "The type of value", - "enum": [ - "formula-number" - ], + "const": "location", "type": "string" }, "data": { "oneOf": [ { - "$ref": "#/components/schemas/FormulaNumber" + "$ref": "#/components/schemas/Location" }, { "type": "null" @@ -3319,22 +2698,23 @@ ], "type": "object" }, - "DropdownsValue": { + "LocationsValue": { + "title": "LocationsValue", "properties": { "type": { "description": "The type of value", - "enum": [ - "dropdown-multi" - ], + "const": "location-multi", "type": "string" }, "data": { - "description": "The value for many dropdown items", + "description": "The values for many locations", "items": { - "$ref": "#/components/schemas/Dropdown" + "$ref": "#/components/schemas/Location" }, - "type": "array", - "nullable": true + "type": [ + "array", + "null" + ] } }, "required": [ @@ -3343,43 +2723,47 @@ ], "type": "object" }, - "Dropdown": { + "PersonValue": { + "title": "PersonValue", "properties": { - "dropdownOptionId": { - "description": "Dropdown item's unique identifier", - "example": 1, - "format": "int64", - "type": "integer" - }, - "text": { - "description": "Dropdown item text", - "example": "first", + "type": { + "description": "The type of value", + "const": "person", "type": "string" + }, + "data": { + "oneOf": [ + { + "$ref": "#/components/schemas/PersonData" + }, + { + "type": "null" + } + ] } }, "required": [ - "dropdownOptionId", - "text" + "data", + "type" ], "type": "object" }, - "DropdownValue": { + "PersonsValue": { + "title": "PersonsValue", "properties": { "type": { "description": "The type of value", - "enum": [ - "dropdown" - ], + "const": "person-multi", "type": "string" }, "data": { - "oneOf": [ - { - "$ref": "#/components/schemas/Dropdown" - }, - { - "type": "null" - } + "description": "The values for many persons", + "items": { + "$ref": "#/components/schemas/PersonData" + }, + "type": [ + "array", + "null" ] } }, @@ -3393,26 +2777,36 @@ "properties": { "dropdownOptionId": { "description": "Dropdown item's unique identifier", - "example": 1, + "examples": [ + 1 + ], "format": "int64", "type": "integer" }, "text": { "description": "Dropdown item text", - "example": "first", + "examples": [ + "first" + ], "type": "string" }, "rank": { "description": "Dropdown item rank", - "example": 0, + "examples": [ + 0 + ], "format": "int64", "type": "integer" }, "color": { "description": "Dropdown item color", - "example": "white", - "type": "string", - "nullable": true + "examples": [ + "white" + ], + "type": [ + "string", + "null" + ] } }, "required": [ @@ -3424,12 +2818,11 @@ "type": "object" }, "RankedDropdownValue": { + "title": "RankedDropdownValue", "properties": { "type": { "description": "The type of value", - "enum": [ - "ranked-dropdown" - ], + "const": "ranked-dropdown", "type": "string" }, "data": { @@ -3449,31 +2842,8 @@ ], "type": "object" }, - "TextsValue": { - "properties": { - "type": { - "description": "The type of value", - "enum": [ - "filterable-text-multi" - ], - "type": "string" - }, - "data": { - "description": "The value for many strings", - "items": { - "type": "string" - }, - "type": "array", - "nullable": true - } - }, - "required": [ - "data", - "type" - ], - "type": "object" - }, "TextValue": { + "title": "TextValue", "properties": { "type": { "description": "The type of value", @@ -3481,13 +2851,17 @@ "filterable-text", "text" ], - "example": "filterable-text", + "examples": [ + "filterable-text" + ], "type": "string" }, "data": { "description": "The value for a string", - "type": "string", - "nullable": true + "type": [ + "string", + "null" + ] } }, "required": [ @@ -3496,20 +2870,23 @@ ], "type": "object" }, - "DateValue": { + "TextsValue": { + "title": "TextsValue", "properties": { "type": { "description": "The type of value", - "enum": [ - "datetime" - ], + "const": "filterable-text-multi", "type": "string" }, "data": { - "description": "The value for a date", - "format": "date-time", - "type": "string", - "nullable": true + "description": "The value for many strings", + "items": { + "type": "string" + }, + "type": [ + "array", + "null" + ] } }, "required": [ @@ -3518,449 +2895,692 @@ ], "type": "object" }, - "FloatsValue": { - "properties": { - "type": { - "description": "The type of value", - "enum": [ - "number-multi" - ], - "type": "string" - }, - "data": { - "description": "The value for many numbers", - "items": { - "type": "number" + "FieldValue": { + "examples": [ + { + "data": { + "continent": "North America", + "country": "United States", + "streetAddress": "170 Columbus Ave", + "city": "San Francisco", + "state": "California" }, - "type": "array", - "nullable": true + "type": "location" } - }, - "required": [ - "data", - "type" ], - "type": "object" - }, - "FloatValue": { "properties": { "type": { "description": "The type of value", "enum": [ - "number" + "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" ], "type": "string" - }, - "data": { - "description": "The value for a number", - "type": "number", - "nullable": true } }, "required": [ - "data", "type" ], - "type": "object" - }, - "LocationsValue": { + "type": "object", + "discriminator": { + "propertyName": "type", + "mapping": { + "company-multi": "#/components/schemas/CompaniesValue", + "company": "#/components/schemas/CompanyValue", + "datetime": "#/components/schemas/DateValue", + "dropdown": "#/components/schemas/DropdownValue", + "dropdown-multi": "#/components/schemas/DropdownsValue", + "number": "#/components/schemas/FloatValue", + "number-multi": "#/components/schemas/FloatsValue", + "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", + "filterable-text": "#/components/schemas/TextValue", + "text": "#/components/schemas/TextValue", + "filterable-text-multi": "#/components/schemas/TextsValue" + } + }, + "oneOf": [ + { + "$ref": "#/components/schemas/CompaniesValue" + }, + { + "$ref": "#/components/schemas/CompanyValue" + }, + { + "$ref": "#/components/schemas/DateValue" + }, + { + "$ref": "#/components/schemas/DropdownValue" + }, + { + "$ref": "#/components/schemas/DropdownsValue" + }, + { + "$ref": "#/components/schemas/FloatValue" + }, + { + "$ref": "#/components/schemas/FloatsValue" + }, + { + "$ref": "#/components/schemas/FormulaValue" + }, + { + "$ref": "#/components/schemas/InteractionValue" + }, + { + "$ref": "#/components/schemas/LocationValue" + }, + { + "$ref": "#/components/schemas/LocationsValue" + }, + { + "$ref": "#/components/schemas/PersonValue" + }, + { + "$ref": "#/components/schemas/PersonsValue" + }, + { + "$ref": "#/components/schemas/RankedDropdownValue" + }, + { + "$ref": "#/components/schemas/TextValue" + }, + { + "$ref": "#/components/schemas/TextsValue" + } + ] + }, + "Field": { + "examples": [ + { + "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" + } + } + ], "properties": { + "id": { + "description": "The field's unique identifier", + "examples": [ + "affinity-data-location" + ], + "type": "string" + }, + "name": { + "description": "The field's name", + "examples": [ + "Location" + ], + "type": "string" + }, "type": { - "description": "The type of value", + "description": "The field's type", "enum": [ - "location-multi" + "enriched", + "global", + "list", + "relationship-intelligence" + ], + "examples": [ + "enriched" ], "type": "string" }, - "data": { - "description": "The values for many locations", - "items": { - "$ref": "#/components/schemas/Location" - }, - "type": "array", - "nullable": true + "enrichmentSource": { + "description": "The source of the data in this Field (if it is enriched)", + "enum": [ + "affinity-data", + "dealroom", + null + ], + "examples": [ + "affinity-data" + ], + "type": [ + "string", + "null" + ] + }, + "value": { + "$ref": "#/components/schemas/FieldValue" } }, "required": [ - "data", - "type" + "enrichmentSource", + "id", + "name", + "type", + "value" ], "type": "object" }, - "LocationValue": { - "properties": { - "type": { - "description": "The type of value", - "enum": [ - "location" + "Company": { + "description": "Company model", + "examples": [ + { + "domain": "acme.co", + "name": "Acme", + "isGlobal": true, + "domains": [ + "acme.co" ], - "type": "string" - }, - "data": { - "oneOf": [ + "id": 1, + "fields": [ { - "$ref": "#/components/schemas/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" + } }, { - "type": "null" + "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" + } } ] } - }, - "required": [ - "data", - "type" - ], - "type": "object" - }, - "CompaniesValue": { - "properties": { - "type": { - "description": "The type of value", - "enum": [ - "company-multi" - ], - "type": "string" - }, - "data": { - "description": "The values for many companies", - "items": { - "$ref": "#/components/schemas/CompanyData" - }, - "type": "array", - "nullable": true - } - }, - "required": [ - "data", - "type" ], - "type": "object" - }, - "CompanyData": { "properties": { "id": { "description": "The company's unique identifier", - "example": 1, + "examples": [ + 1 + ], "format": "int64", "type": "integer" }, "name": { "description": "The company's name", - "example": "Acme", + "examples": [ + "Acme" + ], "type": "string" }, "domain": { "description": "The company's primary domain", - "example": "acme.co", + "examples": [ + "acme.co" + ], "format": "hostname", "type": "string" + }, + "domains": { + "description": "All of the company's domains", + "examples": [ + [ + "acme.co" + ] + ], + "items": { + "format": "hostname", + "type": "string" + }, + "type": "array" + }, + "isGlobal": { + "description": "Whether or not the company is org specific", + "examples": [ + true + ], + "type": "boolean" + }, + "fields": { + "description": "The fields associated with the company", + "items": { + "$ref": "#/components/schemas/Field" + }, + "type": "array" } }, "required": [ "domain", + "domains", "id", + "isGlobal", "name" ], "type": "object" }, - "CompanyValue": { + "Pagination": { + "examples": [ + { + "prevUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgYmVmb3JlOjo6Nw", + "nextUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgIGFmdGVyOjo6NA" + } + ], "properties": { - "type": { - "description": "The type of value", - "enum": [ - "company" + "prevUrl": { + "description": "URL for the previous page", + "examples": [ + "https://api.affinity.co/v2/foo?cursor=ICAgICAgYmVmb3JlOjo6Nw" ], - "type": "string" + "format": "url", + "type": [ + "string", + "null" + ] }, - "data": { - "oneOf": [ - { - "$ref": "#/components/schemas/CompanyData" - }, - { - "type": "null" - } + "nextUrl": { + "description": "URL for the next page", + "examples": [ + "https://api.affinity.co/v2/foo?cursor=ICAgICAgIGFmdGVyOjo6NA" + ], + "format": "url", + "type": [ + "string", + "null" ] } }, - "required": [ - "data", - "type" - ], "type": "object" }, - "PersonsValue": { + "CompanyPaged": { + "description": "CompanyPaged model", + "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" + } + } + ] + } + ] + } + ], "properties": { - "type": { - "description": "The type of value", - "enum": [ - "person-multi" - ], - "type": "string" - }, "data": { - "description": "The values for many persons", + "description": "A page of Company results", "items": { - "$ref": "#/components/schemas/PersonData" + "$ref": "#/components/schemas/Company" }, - "type": "array", - "nullable": true + "type": "array" + }, + "pagination": { + "$ref": "#/components/schemas/Pagination" } }, "required": [ "data", - "type" + "pagination" ], "type": "object" }, - "PersonValue": { + "ValidationError": { + "examples": [ + { + "code": "validation", + "param": "limit", + "message": "🚨 Error! Sound the alarm! 🚨" + } + ], "properties": { - "type": { - "description": "The type of value", - "enum": [ - "person" - ], + "code": { + "description": "Error code", + "const": "validation", "type": "string" }, - "data": { - "oneOf": [ + "message": { + "description": "Error message", + "type": "string" + }, + "param": { + "description": "Param the error refers to", + "type": "string" + } + }, + "required": [ + "code", + "message", + "param" + ], + "type": "object" + }, + "ValidationErrors": { + "description": "ValidationErrors model", + "examples": [ + { + "errors": [ { - "$ref": "#/components/schemas/PersonData" + "code": "validation", + "param": "limit", + "message": "🚨 Error! Sound the alarm! 🚨" }, { - "type": "null" + "code": "validation", + "param": "limit", + "message": "🚨 Error! Sound the alarm! 🚨" } ] } + ], + "properties": { + "errors": { + "description": "ValidationError errors", + "items": { + "$ref": "#/components/schemas/ValidationError" + }, + "type": "array" + } }, "required": [ - "data", - "type" + "errors" ], "type": "object" }, - "ListEntryPaged": { - "description": "ListEntryPaged model", - "example": { - "pagination": { - "prevUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgYmVmb3JlOjo6Nw", - "nextUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgIGFmdGVyOjo6NA" + "AuthorizationError": { + "examples": [ + { + "code": "authorization", + "message": "🚨 Error! Sound the alarm! 🚨" + } + ], + "properties": { + "code": { + "description": "Error code", + "const": "authorization", + "type": "string" }, - "data": [ - { - "listId": 1, - "createdAt": "2023-01-01 00:00:00.000000000 Z", - "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-01 00:00:00.000000000 Z", - "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" - } - } - ] - } - ] + "message": { + "description": "Error message", + "type": "string" + } }, + "required": [ + "code", + "message" + ], + "type": "object" + }, + "AuthorizationErrors": { + "description": "AuthorizationErrors model", + "examples": [ + { + "errors": [ + { + "code": "authorization", + "message": "🚨 Error! Sound the alarm! 🚨" + }, + { + "code": "authorization", + "message": "🚨 Error! Sound the alarm! 🚨" + } + ] + } + ], "properties": { - "data": { - "description": "A page of ListEntry results", + "errors": { + "description": "AuthorizationError errors", "items": { - "$ref": "#/components/schemas/ListEntry" + "$ref": "#/components/schemas/AuthorizationError" }, "type": "array" - }, - "pagination": { - "$ref": "#/components/schemas/Pagination" } }, "required": [ - "data", - "pagination" + "errors" ], "type": "object" }, - "ListEntry": { - "example": { - "listId": 1, - "createdAt": "2023-01-01 00:00:00.000000000 Z", - "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" - } - } - ] - }, + "FieldMetadata": { + "examples": [ + { + "enrichmentSource": "affinity-data", + "valueType": "location", + "name": "Location", + "id": "affinity-data-location", + "type": "enriched" + } + ], "properties": { "id": { - "description": "The list entry's unique identifier", - "example": 1, - "format": "int64", - "type": "integer" + "description": "The field's unique identifier", + "examples": [ + "affinity-data-location" + ], + "type": "string" }, - "listId": { - "description": "The ID of the list that this list entry belongs to", - "example": 1, - "format": "int64", - "type": "integer" + "name": { + "description": "The field's name", + "examples": [ + "Location" + ], + "type": "string" }, - "createdAt": { - "description": "The date that the list entry was created", - "example": "2023-01-01 00:00:00.000000000 Z", - "format": "date-time", + "type": { + "description": "The field's type", + "enum": [ + "enriched", + "global", + "list", + "relationship-intelligence" + ], + "examples": [ + "enriched" + ], "type": "string" }, - "creatorId": { - "description": "The ID of the user that created this list entry", - "example": 1, - "format": "int64", - "type": "integer", - "nullable": true + "enrichmentSource": { + "description": "The source of the data in this Field (if it is enriched)", + "enum": [ + "affinity-data", + "dealroom", + null + ], + "examples": [ + "affinity-data" + ], + "type": [ + "string", + "null" + ] }, - "fields": { - "description": "The fields associated with the list entry", - "items": { - "$ref": "#/components/schemas/Field" - }, - "type": "array" + "valueType": { + "description": "The type of the data in this Field", + "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" + ], + "type": "string" } }, "required": [ - "createdAt", - "creatorId", - "fields", + "enrichmentSource", "id", - "listId" + "name", + "type", + "valueType" ], "type": "object" }, - "ListPaged": { - "description": "ListPaged model", - "example": { - "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 + "FieldMetadataPaged": { + "description": "FieldMetadataPaged model", + "examples": [ + { + "pagination": { + "prevUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgYmVmb3JlOjo6Nw", + "nextUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgIGFmdGVyOjo6NA" }, - { - "name": "All companies", - "creatorId": 1, - "isPublic": false, - "id": 1, - "ownerId": 1 - } - ] - }, + "data": [ + { + "enrichmentSource": "affinity-data", + "valueType": "location", + "name": "Location", + "id": "affinity-data-location", + "type": "enriched" + }, + { + "enrichmentSource": "affinity-data", + "valueType": "location", + "name": "Location", + "id": "affinity-data-location", + "type": "enriched" + } + ] + } + ], "properties": { "data": { - "description": "A page of List results", + "description": "A page of FieldMetadata results", "items": { - "$ref": "#/components/schemas/List" + "$ref": "#/components/schemas/FieldMetadata" }, "type": "array" }, @@ -3975,40 +3595,52 @@ "type": "object" }, "List": { - "example": { - "name": "All companies", - "creatorId": 1, - "isPublic": false, - "id": 1, - "ownerId": 1 - }, + "examples": [ + { + "name": "All companies", + "creatorId": 1, + "isPublic": false, + "id": 1, + "ownerId": 1 + } + ], "properties": { "id": { "description": "The unique identifier for the list", - "example": 1, + "examples": [ + 1 + ], "format": "int64", "type": "integer" }, "name": { "description": "The name of the list", - "example": "All companies", + "examples": [ + "All companies" + ], "type": "string" }, "creatorId": { "description": "The ID of the user that created this list", - "example": 1, + "examples": [ + 1 + ], "format": "int64", "type": "integer" }, "ownerId": { "description": "The ID of the user that owns this list", - "example": 1, + "examples": [ + 1 + ], "format": "int64", "type": "integer" }, "isPublic": { "description": "Whether or not the list is public", - "example": false, + "examples": [ + false + ], "type": "boolean" } }, @@ -4021,242 +3653,423 @@ ], "type": "object" }, - "Errors": { + "ListPaged": { + "description": "ListPaged model", + "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 + } + ] + } + ], "properties": { - "errors": { - "description": "Errors", + "data": { + "description": "A page of List results", "items": { - "$ref": "#/components/schemas/Error" + "$ref": "#/components/schemas/List" }, - "type": "array", - "nullable": true + "type": "array" + }, + "pagination": { + "$ref": "#/components/schemas/Pagination" } }, + "required": [ + "data", + "pagination" + ], "type": "object" }, - "Error": { - "properties": { - "code": { - "description": "Error code", - "type": "string", - "nullable": true - } - }, - "type": "object", - "discriminator": { - "propertyName": "code", - "mapping": { - "authentication": "#/components/schemas/AuthenticationError", - "authorization": "#/components/schemas/AuthorizationError", - "conflict": "#/components/schemas/ConflictError", - "method-not-allowed": "#/components/schemas/MethodNotAllowedError", - "not-found": "#/components/schemas/NotFoundError", - "server": "#/components/schemas/ServerError", - "validation": "#/components/schemas/ValidationError", - "empty-message-body": "#/components/schemas/EmptyMessageBodyError", - "invalid-accept-header": "#/components/schemas/InvalidAcceptHeaderError", - "invalid-message-body": "#/components/schemas/InvalidMessageBodyError", - "invalid-version-header": "#/components/schemas/InvalidVersionHeaderError", - "too-many-multipart-files": "#/components/schemas/TooManyMultipartFilesError", - "rate-limit": "#/components/schemas/RateLimitError", - "error": "#/components/schemas/GenericError" - } - }, - "oneOf": [ - { - "$ref": "#/components/schemas/AuthenticationError" - }, - { - "$ref": "#/components/schemas/AuthorizationError" - }, - { - "$ref": "#/components/schemas/ConflictError" - }, - { - "$ref": "#/components/schemas/MethodNotAllowedError" - }, - { - "$ref": "#/components/schemas/NotFoundError" - }, - { - "$ref": "#/components/schemas/ServerError" - }, - { - "$ref": "#/components/schemas/ValidationError" - }, - { - "$ref": "#/components/schemas/EmptyMessageBodyError" - }, - { - "$ref": "#/components/schemas/InvalidAcceptHeaderError" - }, - { - "$ref": "#/components/schemas/InvalidMessageBodyError" - }, - { - "$ref": "#/components/schemas/InvalidVersionHeaderError" - }, - { - "$ref": "#/components/schemas/TooManyMultipartFilesError" - }, - { - "$ref": "#/components/schemas/RateLimitError" - }, + "ListEntry": { + "examples": [ { - "$ref": "#/components/schemas/GenericError" + "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" + } + } + ] } - ] - }, - "Grant": { - "example": { - "createdAt": "2023-01-01 00:00:00.000000000 Z", - "scopes": [ - "api" - ], - "type": "api-key" - }, + ], "properties": { - "type": { - "description": "The type of grant used to authenticate", - "enum": [ - "api-key" + "id": { + "description": "The list entry's unique identifier", + "examples": [ + 1 ], - "example": "api-key", - "type": "string" + "format": "int64", + "type": "integer" }, - "scopes": { - "description": "The scopes available to the current grant", - "example": [ - "api" + "listId": { + "description": "The ID of the list that this list entry belongs to", + "examples": [ + 1 ], - "items": { - "type": "string" - }, - "type": "array" + "format": "int64", + "type": "integer" }, "createdAt": { - "description": "When the grant was created", - "example": "2023-01-01 00:00:00.000000000 Z", + "description": "The date that the list entry was created", + "examples": [ + "2023-01-01T00:00:00Z" + ], "format": "date-time", "type": "string" + }, + "creatorId": { + "description": "The ID of the user that created this list entry", + "examples": [ + 1 + ], + "format": "int64", + "type": [ + "integer", + "null" + ] + }, + "fields": { + "description": "The fields associated with the list entry", + "items": { + "$ref": "#/components/schemas/Field" + }, + "type": "array" } }, "required": [ "createdAt", - "scopes", - "type" + "creatorId", + "fields", + "id", + "listId" ], "type": "object" }, - "User": { - "example": { - "firstName": "John", - "lastName": "Smith", - "emailAddress": "john.smith@contoso.com", - "id": 1 - }, + "ListEntryPaged": { + "description": "ListEntryPaged model", + "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-01 00:00:00.000000000 Z", + "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-01 00:00:00.000000000 Z", + "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" + } + } + ] + } + ] + } + ], "properties": { - "id": { - "description": "The user's unique identifier", - "example": 1, - "format": "int64", - "type": "integer" - }, - "firstName": { - "description": "The user's first name", - "example": "John", - "type": "string" - }, - "lastName": { - "description": "The user's last name", - "example": "Smith", - "type": "string", - "nullable": true + "data": { + "description": "A page of ListEntry results", + "items": { + "$ref": "#/components/schemas/ListEntry" + }, + "type": "array" }, - "emailAddress": { - "description": "The user's email address", - "example": "john.smith@contoso.com", - "format": "email", - "type": "string" + "pagination": { + "$ref": "#/components/schemas/Pagination" } }, "required": [ - "emailAddress", - "firstName", - "id", - "lastName" + "data", + "pagination" ], "type": "object" }, - "Tenant": { - "example": { - "name": "Contoso Ltd.", - "subdomain": "contoso", - "id": 1 - }, + "ListWithType": { + "description": "ListWithType model", + "examples": [ + { + "name": "All companies", + "creatorId": 1, + "isPublic": false, + "id": 1, + "ownerId": 1, + "type": "company" + } + ], "properties": { "id": { - "description": "The tenant's unique identifier", - "example": 1, + "description": "The unique identifier for the list", + "examples": [ + 1 + ], "format": "int64", "type": "integer" }, "name": { - "description": "The name of the tenant", - "example": "Contoso Ltd.", + "description": "The name of the list", + "examples": [ + "All companies" + ], "type": "string" }, - "subdomain": { - "description": "The tenant's subdomain under affinity.co", - "example": "contoso", - "format": "hostname", + "creatorId": { + "description": "The ID of the user that created this list", + "examples": [ + 1 + ], + "format": "int64", + "type": "integer" + }, + "ownerId": { + "description": "The ID of the user that owns this list", + "examples": [ + 1 + ], + "format": "int64", + "type": "integer" + }, + "isPublic": { + "description": "Whether or not the list is public", + "examples": [ + false + ], + "type": "boolean" + }, + "type": { + "description": "The entity type for this list", + "enum": [ + "company", + "opportunity", + "person" + ], + "examples": [ + "company" + ], "type": "string" } }, "required": [ + "creatorId", "id", + "isPublic", "name", - "subdomain" + "ownerId", + "type" ], "type": "object" }, - "WhoAmI": { - "description": "WhoAmI model", - "example": { - "grant": { - "createdAt": "2023-01-01 00:00:00.000000000 Z", - "scopes": [ - "api" - ], - "type": "api-key" - }, - "user": { - "firstName": "John", - "lastName": "Smith", - "emailAddress": "john.smith@contoso.com", - "id": 1 + "ListWithTypePaged": { + "description": "ListWithTypePaged model", + "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, + "type": "company" + }, + { + "name": "All companies", + "creatorId": 1, + "isPublic": false, + "id": 1, + "ownerId": 1, + "type": "company" + } + ] + } + ], + "properties": { + "data": { + "description": "A page of ListWithType results", + "items": { + "$ref": "#/components/schemas/ListWithType" + }, + "type": "array" }, - "tenant": { - "name": "Contoso Ltd.", - "subdomain": "contoso", - "id": 1 + "pagination": { + "$ref": "#/components/schemas/Pagination" } }, + "required": [ + "data", + "pagination" + ], + "type": "object" + }, + "CompanyListEntry": { "properties": { - "tenant": { - "$ref": "#/components/schemas/Tenant" + "id": { + "description": "The list entry's unique identifier", + "examples": [ + 1 + ], + "format": "int64", + "type": "integer" }, - "user": { - "$ref": "#/components/schemas/User" + "type": { + "description": "The entity type for this list entry", + "const": "company", + "examples": [ + "company" + ], + "type": "string" }, - "grant": { - "$ref": "#/components/schemas/Grant" + "createdAt": { + "description": "The date that the list entry was created", + "examples": [ + "2023-01-01T00:00:00Z" + ], + "format": "date-time", + "type": "string" + }, + "creatorId": { + "description": "The ID of the user that created this list entry", + "examples": [ + 1 + ], + "format": "int64", + "type": [ + "integer", + "null" + ] + }, + "entity": { + "$ref": "#/components/schemas/Company" } }, "required": [ - "grant", - "tenant", - "user" + "createdAt", + "creatorId", + "entity", + "id", + "type" ], "type": "object" }, @@ -4264,18 +4077,24 @@ "properties": { "id": { "description": "The unique identifier for the opportunity", - "example": 1, + "examples": [ + 1 + ], "format": "int64", "type": "integer" }, "name": { "description": "The name of the opportunity", - "example": "Acme Upsell $10k", + "examples": [ + "Acme Upsell $10k" + ], "type": "string" }, "listId": { "description": "The ID of the list that the opportunity belongs to", - "example": 1, + "examples": [ + 1 + ], "format": "int64", "type": "integer" }, @@ -4294,37 +4113,45 @@ ], "type": "object" }, - "PersonListEntry": { + "OpportunityListEntry": { "properties": { "id": { "description": "The list entry's unique identifier", - "example": 1, + "examples": [ + 1 + ], "format": "int64", "type": "integer" }, "type": { "description": "The entity type for this list entry", - "enum": [ - "person" + "const": "opportunity", + "examples": [ + "opportunity" ], - "example": "person", "type": "string" }, "createdAt": { "description": "The date that the list entry was created", - "example": "2023-01-01 00:00:00.000000000 Z", + "examples": [ + "2023-01-01T00:00:00Z" + ], "format": "date-time", "type": "string" }, "creatorId": { "description": "The ID of the user that created this list entry", - "example": 1, + "examples": [ + 1 + ], "format": "int64", - "type": "integer", - "nullable": true + "type": [ + "integer", + "null" + ] }, "entity": { - "$ref": "#/components/schemas/Person" + "$ref": "#/components/schemas/OpportunityWithFields" } }, "required": [ @@ -4336,37 +4163,174 @@ ], "type": "object" }, - "OpportunityListEntry": { + "Person": { + "description": "Person model", + "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": "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" + } + ], + "properties": { + "id": { + "description": "The persons's unique identifier", + "examples": [ + 1 + ], + "format": "int64", + "type": "integer" + }, + "firstName": { + "description": "The person's first name", + "examples": [ + "Jane" + ], + "type": "string" + }, + "lastName": { + "description": "The person's last name", + "examples": [ + "Doe" + ], + "type": [ + "string", + "null" + ] + }, + "primaryEmailAddress": { + "description": "The person's primary email address", + "examples": [ + "jane.doe@acme.co" + ], + "format": "email", + "type": [ + "string", + "null" + ] + }, + "emailAddresses": { + "description": "All of the person's email addresses", + "examples": [ + [ + "jane.doe@acme.co", + "janedoe@gmail.com" + ] + ], + "items": { + "format": "email", + "type": "string" + }, + "type": "array" + }, + "type": { + "description": "The person's type", + "enum": [ + "internal", + "external" + ], + "examples": [ + "internal" + ], + "type": "string" + }, + "fields": { + "description": "The fields associated with the person", + "items": { + "$ref": "#/components/schemas/Field" + }, + "type": "array" + } + }, + "required": [ + "emailAddresses", + "firstName", + "id", + "lastName", + "primaryEmailAddress", + "type" + ], + "type": "object" + }, + "PersonListEntry": { "properties": { "id": { "description": "The list entry's unique identifier", - "example": 1, + "examples": [ + 1 + ], "format": "int64", "type": "integer" }, "type": { "description": "The entity type for this list entry", - "enum": [ - "opportunity" + "const": "person", + "examples": [ + "person" ], - "example": "opportunity", "type": "string" }, "createdAt": { "description": "The date that the list entry was created", - "example": "2023-01-01 00:00:00.000000000 Z", + "examples": [ + "2023-01-01T00:00:00Z" + ], "format": "date-time", "type": "string" }, "creatorId": { "description": "The ID of the user that created this list entry", - "example": 1, + "examples": [ + 1 + ], "format": "int64", - "type": "integer", - "nullable": true + "type": [ + "integer", + "null" + ] }, "entity": { - "$ref": "#/components/schemas/OpportunityWithFields" + "$ref": "#/components/schemas/Person" } }, "required": [ @@ -4378,421 +4342,525 @@ ], "type": "object" }, - "CompanyListEntry": { + "ListEntryWithEntity": { + "examples": [ + { + "createdAt": "2023-01-01 00:00:00.000000000 Z", + "creatorId": 1, + "id": 1, + "type": "company", + "entity": { + "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" + } + } + ] + } + } + ], "properties": { - "id": { - "description": "The list entry's unique identifier", - "example": 1, - "format": "int64", - "type": "integer" - }, "type": { "description": "The entity type for this list entry", "enum": [ + "company", + "opportunity", + "person" + ], + "examples": [ "company" ], - "example": "company", - "type": "string" - }, - "createdAt": { - "description": "The date that the list entry was created", - "example": "2023-01-01 00:00:00.000000000 Z", - "format": "date-time", "type": "string" - }, - "creatorId": { - "description": "The ID of the user that created this list entry", - "example": 1, - "format": "int64", - "type": "integer", - "nullable": true - }, - "entity": { - "$ref": "#/components/schemas/Company" } }, "required": [ - "createdAt", - "creatorId", - "entity", - "id", "type" ], - "type": "object" - }, - "AuthenticationErrors": { - "description": "AuthenticationErrors model", - "example": { - "errors": [ - { - "code": "authentication", - "message": "🚨 Error! Sound the alarm! 🚨" - }, - { - "code": "authentication", - "message": "🚨 Error! Sound the alarm! 🚨" - } - ] - }, - "properties": { - "errors": { - "description": "AuthenticationError errors", - "items": { - "$ref": "#/components/schemas/AuthenticationError" - }, - "type": "array", - "nullable": true - } - }, - "type": "object" - }, - "AuthenticationError": { - "example": { - "code": "authentication", - "message": "🚨 Error! Sound the alarm! 🚨" - }, - "properties": { - "code": { - "description": "Error code", - "example": "authentication", - "type": "string", - "nullable": true - }, - "message": { - "description": "Error message", - "example": "🚨 Error! Sound the alarm! 🚨", - "type": "string", - "nullable": true - } - }, - "type": "object" - }, - "AuthorizationErrors": { - "description": "AuthorizationErrors model", - "example": { - "errors": [ - { - "code": "authorization", - "message": "🚨 Error! Sound the alarm! 🚨" - }, - { - "code": "authorization", - "message": "🚨 Error! Sound the alarm! 🚨" - } - ] - }, - "properties": { - "errors": { - "description": "AuthorizationError errors", - "items": { - "$ref": "#/components/schemas/AuthorizationError" - }, - "type": "array", - "nullable": true - } - }, - "type": "object" - }, - "AuthorizationError": { - "example": { - "code": "authorization", - "message": "🚨 Error! Sound the alarm! 🚨" - }, - "properties": { - "code": { - "description": "Error code", - "example": "authorization", - "type": "string", - "nullable": true - }, - "message": { - "description": "Error message", - "example": "🚨 Error! Sound the alarm! 🚨", - "type": "string", - "nullable": true - } - }, - "type": "object" - }, - "ValidationErrors": { - "description": "ValidationErrors model", - "example": { - "errors": [ - { - "code": "validation", - "param": "limit", - "message": "🚨 Error! Sound the alarm! 🚨" - }, - { - "code": "validation", - "param": "limit", - "message": "🚨 Error! Sound the alarm! 🚨" - } - ] - }, - "properties": { - "errors": { - "description": "ValidationError errors", - "items": { - "$ref": "#/components/schemas/ValidationError" - }, - "type": "array", - "nullable": true + "type": "object", + "discriminator": { + "propertyName": "type", + "mapping": { + "company": "#/components/schemas/CompanyListEntry", + "opportunity": "#/components/schemas/OpportunityListEntry", + "person": "#/components/schemas/PersonListEntry" } }, - "type": "object" - }, - "ValidationError": { - "example": { - "code": "validation", - "param": "limit", - "message": "🚨 Error! Sound the alarm! 🚨" - }, - "properties": { - "code": { - "description": "Error code", - "example": "validation", - "type": "string", - "nullable": true + "oneOf": [ + { + "$ref": "#/components/schemas/CompanyListEntry" }, - "message": { - "description": "Error message", - "example": "🚨 Error! Sound the alarm! 🚨", - "type": "string", - "nullable": true + { + "$ref": "#/components/schemas/OpportunityListEntry" }, - "param": { - "description": "Param the error refers to", - "example": "limit", - "type": "string", - "nullable": true + { + "$ref": "#/components/schemas/PersonListEntry" } - }, - "type": "object" + ] }, - "NotFoundErrors": { - "description": "NotFoundErrors model", - "example": { - "errors": [ - { - "code": "not-found", - "message": "🚨 Error! Sound the alarm! 🚨" - }, - { - "code": "not-found", - "message": "🚨 Error! Sound the alarm! 🚨" - } - ] - }, - "properties": { - "errors": { - "description": "NotFoundError errors", - "items": { - "$ref": "#/components/schemas/NotFoundError" + "ListEntryWithEntityPaged": { + "description": "ListEntryWithEntityPaged model", + "examples": [ + { + "pagination": { + "prevUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgYmVmb3JlOjo6Nw", + "nextUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgIGFmdGVyOjo6NA" }, - "type": "array", - "nullable": true - } - }, - "type": "object" - }, - "NotFoundError": { - "example": { - "code": "not-found", - "message": "🚨 Error! Sound the alarm! 🚨" - }, - "properties": { - "code": { - "description": "Error code", - "example": "not-found", - "type": "string", - "nullable": true - }, - "message": { - "description": "Error message", - "example": "🚨 Error! Sound the alarm! 🚨", - "type": "string", - "nullable": true - } - }, - "type": "object" - }, - "GenericError": { - "properties": { - "code": { - "description": "Error code", - "type": "string", - "nullable": true - }, - "message": { - "description": "Error message", - "example": "🚨 Error! Sound the alarm! 🚨", - "type": "string", - "nullable": true - } - }, - "type": "object" - }, - "RateLimitError": { - "properties": { - "code": { - "description": "Error code", - "example": "rate-limit", - "type": "string", - "nullable": true - }, - "message": { - "description": "Error message", - "example": "🚨 Error! Sound the alarm! 🚨", - "type": "string", - "nullable": true - } - }, - "type": "object" - }, - "TooManyMultipartFilesError": { - "properties": { - "code": { - "description": "Error code", - "example": "too-many-multipart-files", - "type": "string", - "nullable": true - }, - "message": { - "description": "Error message", - "example": "🚨 Error! Sound the alarm! 🚨", - "type": "string", - "nullable": true - } - }, - "type": "object" - }, - "InvalidVersionHeaderError": { - "properties": { - "code": { - "description": "Error code", - "example": "invalid-version-header", - "type": "string", - "nullable": true - }, - "message": { - "description": "Error message", - "example": "🚨 Error! Sound the alarm! 🚨", - "type": "string", - "nullable": true + "data": [ + { + "createdAt": "2023-01-01 00:00:00.000000000 Z", + "creatorId": 1, + "id": 1, + "type": "company", + "entity": { + "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" + } + } + ] + } + }, + { + "createdAt": "2023-01-01 00:00:00.000000000 Z", + "creatorId": 1, + "id": 1, + "type": "company", + "entity": { + "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" + } + } + ] + } + } + ] } - }, - "type": "object" - }, - "InvalidMessageBodyError": { + ], "properties": { - "code": { - "description": "Error code", - "example": "invalid-message-body", - "type": "string", - "nullable": true + "data": { + "description": "A page of ListEntryWithEntity results", + "items": { + "$ref": "#/components/schemas/ListEntryWithEntity" + }, + "type": [ + "array", + "null" + ] }, - "message": { - "description": "Error message", - "example": "🚨 Error! Sound the alarm! 🚨", - "type": "string", - "nullable": true + "pagination": { + "$ref": "#/components/schemas/Pagination" } }, + "required": [ + "data", + "pagination" + ], "type": "object" }, - "InvalidAcceptHeaderError": { + "SavedView": { + "description": "SavedView model", + "examples": [ + { + "createdAt": "2023-01-01T00:00:00Z", + "name": "my interesting companies", + "id": 28, + "type": "sheet" + } + ], "properties": { - "code": { - "description": "Error code", - "example": "invalid-accept-header", - "type": "string", - "nullable": true + "id": { + "description": "The saved view's unique identifier", + "examples": [ + 28 + ], + "format": "int64", + "type": "integer" }, - "message": { - "description": "Error message", - "example": "🚨 Error! Sound the alarm! 🚨", - "type": "string", - "nullable": true + "name": { + "description": "The saved view's name", + "examples": [ + "my interesting companies" + ], + "type": "string" + }, + "type": { + "description": "The type for this saved view", + "enum": [ + "sheet", + "board", + "dashboard" + ], + "examples": [ + "sheet" + ], + "type": "string" + }, + "createdAt": { + "description": "The date that the saved view was created", + "examples": [ + "2023-01-01T00:00:00Z" + ], + "format": "date-time", + "type": "string" } }, + "required": [ + "createdAt", + "id", + "name", + "type" + ], "type": "object" }, - "EmptyMessageBodyError": { + "SavedViewPaged": { + "description": "SavedViewPaged model", + "examples": [ + { + "pagination": { + "prevUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgYmVmb3JlOjo6Nw", + "nextUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgIGFmdGVyOjo6NA" + }, + "data": [ + { + "createdAt": "2023-01-01 00:00:00.000000000 Z", + "name": "my interesting companies", + "id": 28, + "type": "sheet" + }, + { + "createdAt": "2023-01-01 00:00:00.000000000 Z", + "name": "my interesting companies", + "id": 28, + "type": "sheet" + } + ] + } + ], "properties": { - "code": { - "description": "Error code", - "example": "empty-message-body", - "type": "string", - "nullable": true + "data": { + "description": "A page of SavedView results", + "items": { + "$ref": "#/components/schemas/SavedView" + }, + "type": "array" }, - "message": { - "description": "Error message", - "example": "🚨 Error! Sound the alarm! 🚨", - "type": "string", - "nullable": true + "pagination": { + "$ref": "#/components/schemas/Pagination" } }, + "required": [ + "data", + "pagination" + ], "type": "object" }, - "ServerError": { + "Opportunity": { + "description": "Opportunity model", + "examples": [ + { + "listId": 1, + "name": "Acme Upsell $10k", + "id": 1 + } + ], "properties": { - "code": { - "description": "Error code", - "example": "server", - "type": "string", - "nullable": true + "id": { + "description": "The unique identifier for the opportunity", + "examples": [ + 1 + ], + "format": "int64", + "type": "integer" }, - "message": { - "description": "Error message", - "example": "🚨 Error! Sound the alarm! 🚨", - "type": "string", - "nullable": true + "name": { + "description": "The name of the opportunity", + "examples": [ + "Acme Upsell $10k" + ], + "type": "string" + }, + "listId": { + "description": "The ID of the list that the opportunity belongs to", + "examples": [ + 1 + ], + "format": "int64", + "type": "integer" } }, + "required": [ + "id", + "listId", + "name" + ], "type": "object" }, - "MethodNotAllowedError": { + "OpportunityPaged": { + "description": "OpportunityPaged model", + "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 + } + ] + } + ], "properties": { - "code": { - "description": "Error code", - "example": "method-not-allowed", - "type": "string", - "nullable": true + "data": { + "description": "A page of Opportunity results", + "items": { + "$ref": "#/components/schemas/Opportunity" + }, + "type": "array" }, - "message": { - "description": "Error message", - "example": "🚨 Error! Sound the alarm! 🚨", - "type": "string", - "nullable": true + "pagination": { + "$ref": "#/components/schemas/Pagination" } }, + "required": [ + "data", + "pagination" + ], "type": "object" }, - "ConflictError": { + "PersonPaged": { + "description": "PersonPaged model", + "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" + } + ] + } + ], "properties": { - "code": { - "description": "Error code", - "example": "conflict", - "type": "string", - "nullable": true + "data": { + "description": "A page of Person results", + "items": { + "$ref": "#/components/schemas/Person" + }, + "type": "array" }, - "message": { - "description": "Error message", - "example": "🚨 Error! Sound the alarm! 🚨", - "type": "string", - "nullable": true + "pagination": { + "$ref": "#/components/schemas/Pagination" } }, + "required": [ + "data", + "pagination" + ], "type": "object" } - }, - "securitySchemes": { - "bearerAuth": { - "type": "http", - "scheme": "bearer" - } } - }, - "x-original-swagger-version": "2.0" + } } \ No newline at end of file From 01bdec059d2a656c2e04182e41ec2c3d3f6d2cd4 Mon Sep 17 00:00:00 2001 From: Joscha Feth Date: Thu, 26 Sep 2024 10:16:07 +0100 Subject: [PATCH 2/9] chore: regenerated code --- src/v2/generated/.openapi-generator/FILES | 12 -- src/v2/generated/models/Attendee.ts | 2 +- .../generated/models/AuthenticationError.ts | 6 +- .../generated/models/AuthenticationErrors.ts | 4 +- src/v2/generated/models/AuthorizationError.ts | 6 +- .../generated/models/AuthorizationErrors.ts | 4 +- src/v2/generated/models/ChatMessage.ts | 9 +- src/v2/generated/models/CompaniesValue.ts | 13 +-- src/v2/generated/models/Company.ts | 2 +- src/v2/generated/models/CompanyData.ts | 2 +- src/v2/generated/models/CompanyListEntry.ts | 11 +- src/v2/generated/models/CompanyPaged.ts | 2 +- src/v2/generated/models/CompanyValue.ts | 11 +- src/v2/generated/models/ConflictError.ts | 49 -------- src/v2/generated/models/DateValue.ts | 11 +- src/v2/generated/models/Dropdown.ts | 2 +- src/v2/generated/models/DropdownValue.ts | 11 +- src/v2/generated/models/DropdownsValue.ts | 13 +-- src/v2/generated/models/Email.ts | 15 +-- .../generated/models/EmptyMessageBodyError.ts | 49 -------- src/v2/generated/models/Errors.ts | 39 ------- src/v2/generated/models/Field.ts | 2 +- src/v2/generated/models/FieldMetadata.ts | 2 +- src/v2/generated/models/FieldMetadataPaged.ts | 2 +- src/v2/generated/models/FieldValue.ts | 2 +- src/v2/generated/models/FloatValue.ts | 11 +- src/v2/generated/models/FloatsValue.ts | 13 +-- src/v2/generated/models/FormulaNumber.ts | 2 +- src/v2/generated/models/FormulaValue.ts | 11 +- src/v2/generated/models/GenericError.ts | 49 -------- src/v2/generated/models/Grant.ts | 11 +- src/v2/generated/models/Interaction.ts | 2 +- src/v2/generated/models/InteractionValue.ts | 11 +- .../models/InvalidAcceptHeaderError.ts | 49 -------- .../models/InvalidMessageBodyError.ts | 49 -------- .../models/InvalidVersionHeaderError.ts | 49 -------- src/v2/generated/models/List.ts | 2 +- src/v2/generated/models/ListEntry.ts | 2 +- src/v2/generated/models/ListEntryPaged.ts | 2 +- .../generated/models/ListEntryWithEntity.ts | 2 +- .../models/ListEntryWithEntityPaged.ts | 4 +- src/v2/generated/models/ListPaged.ts | 2 +- src/v2/generated/models/ListWithType.ts | 2 +- src/v2/generated/models/ListWithTypePaged.ts | 2 +- src/v2/generated/models/Location.ts | 2 +- src/v2/generated/models/LocationValue.ts | 11 +- src/v2/generated/models/LocationsValue.ts | 13 +-- src/v2/generated/models/Meeting.ts | 11 +- .../generated/models/MethodNotAllowedError.ts | 49 -------- src/v2/generated/models/ModelError.ts | 72 ------------ src/v2/generated/models/NotFoundError.ts | 6 +- src/v2/generated/models/NotFoundErrors.ts | 4 +- src/v2/generated/models/ObjectSerializer.ts | 105 ++++-------------- src/v2/generated/models/Opportunity.ts | 2 +- .../generated/models/OpportunityListEntry.ts | 11 +- src/v2/generated/models/OpportunityPaged.ts | 2 +- .../generated/models/OpportunityWithFields.ts | 2 +- src/v2/generated/models/Pagination.ts | 2 +- src/v2/generated/models/Person.ts | 2 +- src/v2/generated/models/PersonData.ts | 2 +- src/v2/generated/models/PersonListEntry.ts | 11 +- src/v2/generated/models/PersonPaged.ts | 2 +- src/v2/generated/models/PersonValue.ts | 11 +- src/v2/generated/models/PersonsValue.ts | 13 +-- src/v2/generated/models/PhoneCall.ts | 11 +- src/v2/generated/models/RankedDropdown.ts | 2 +- .../generated/models/RankedDropdownValue.ts | 11 +- src/v2/generated/models/RateLimitError.ts | 49 -------- src/v2/generated/models/SavedView.ts | 2 +- src/v2/generated/models/SavedViewPaged.ts | 2 +- src/v2/generated/models/ServerError.ts | 49 -------- src/v2/generated/models/Tenant.ts | 2 +- src/v2/generated/models/TextValue.ts | 2 +- src/v2/generated/models/TextsValue.ts | 13 +-- .../models/TooManyMultipartFilesError.ts | 49 -------- src/v2/generated/models/User.ts | 2 +- src/v2/generated/models/ValidationError.ts | 8 +- src/v2/generated/models/ValidationErrors.ts | 4 +- src/v2/generated/models/WhoAmI.ts | 2 +- src/v2/generated/models/all.ts | 12 -- src/v2/generated/types/ObjectParamAPI.ts | 12 -- src/v2/generated/types/ObservableAPI.ts | 12 -- src/v2/generated/types/PromiseAPI.ts | 12 -- 83 files changed, 156 insertions(+), 989 deletions(-) delete mode 100644 src/v2/generated/models/ConflictError.ts delete mode 100644 src/v2/generated/models/EmptyMessageBodyError.ts delete mode 100644 src/v2/generated/models/Errors.ts delete mode 100644 src/v2/generated/models/GenericError.ts delete mode 100644 src/v2/generated/models/InvalidAcceptHeaderError.ts delete mode 100644 src/v2/generated/models/InvalidMessageBodyError.ts delete mode 100644 src/v2/generated/models/InvalidVersionHeaderError.ts delete mode 100644 src/v2/generated/models/MethodNotAllowedError.ts delete mode 100644 src/v2/generated/models/ModelError.ts delete mode 100644 src/v2/generated/models/RateLimitError.ts delete mode 100644 src/v2/generated/models/ServerError.ts delete mode 100644 src/v2/generated/models/TooManyMultipartFilesError.ts diff --git a/src/v2/generated/.openapi-generator/FILES b/src/v2/generated/.openapi-generator/FILES index f5e0c11..b45725e 100644 --- a/src/v2/generated/.openapi-generator/FILES +++ b/src/v2/generated/.openapi-generator/FILES @@ -31,14 +31,11 @@ models/CompanyData.ts models/CompanyListEntry.ts models/CompanyPaged.ts models/CompanyValue.ts -models/ConflictError.ts models/DateValue.ts models/Dropdown.ts models/DropdownValue.ts models/DropdownsValue.ts models/Email.ts -models/EmptyMessageBodyError.ts -models/Errors.ts models/Field.ts models/FieldMetadata.ts models/FieldMetadataPaged.ts @@ -47,13 +44,9 @@ models/FloatValue.ts models/FloatsValue.ts models/FormulaNumber.ts models/FormulaValue.ts -models/GenericError.ts models/Grant.ts models/Interaction.ts models/InteractionValue.ts -models/InvalidAcceptHeaderError.ts -models/InvalidMessageBodyError.ts -models/InvalidVersionHeaderError.ts models/List.ts models/ListEntry.ts models/ListEntryPaged.ts @@ -66,8 +59,6 @@ models/Location.ts models/LocationValue.ts models/LocationsValue.ts models/Meeting.ts -models/MethodNotAllowedError.ts -models/ModelError.ts models/NotFoundError.ts models/NotFoundErrors.ts models/ObjectSerializer.ts @@ -85,14 +76,11 @@ models/PersonsValue.ts models/PhoneCall.ts models/RankedDropdown.ts models/RankedDropdownValue.ts -models/RateLimitError.ts models/SavedView.ts models/SavedViewPaged.ts -models/ServerError.ts models/Tenant.ts models/TextValue.ts models/TextsValue.ts -models/TooManyMultipartFilesError.ts models/User.ts models/ValidationError.ts models/ValidationErrors.ts diff --git a/src/v2/generated/models/Attendee.ts b/src/v2/generated/models/Attendee.ts index 9aaa3ad..066fd95 100644 --- a/src/v2/generated/models/Attendee.ts +++ b/src/v2/generated/models/Attendee.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co diff --git a/src/v2/generated/models/AuthenticationError.ts b/src/v2/generated/models/AuthenticationError.ts index b9e388b..a24c1c3 100644 --- a/src/v2/generated/models/AuthenticationError.ts +++ b/src/v2/generated/models/AuthenticationError.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co @@ -16,11 +16,11 @@ export class AuthenticationError { /** * Error code */ - 'code'?: string | null; + 'code': string; /** * Error message */ - 'message'?: string | null; + 'message': string; static readonly discriminator: string | undefined = undefined; diff --git a/src/v2/generated/models/AuthenticationErrors.ts b/src/v2/generated/models/AuthenticationErrors.ts index 9ed0150..b855524 100644 --- a/src/v2/generated/models/AuthenticationErrors.ts +++ b/src/v2/generated/models/AuthenticationErrors.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co @@ -20,7 +20,7 @@ export class AuthenticationErrors { /** * AuthenticationError errors */ - 'errors'?: Array | null; + 'errors': Array; static readonly discriminator: string | undefined = undefined; diff --git a/src/v2/generated/models/AuthorizationError.ts b/src/v2/generated/models/AuthorizationError.ts index 6451aae..43a2b27 100644 --- a/src/v2/generated/models/AuthorizationError.ts +++ b/src/v2/generated/models/AuthorizationError.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co @@ -16,11 +16,11 @@ export class AuthorizationError { /** * Error code */ - 'code'?: string | null; + 'code': string; /** * Error message */ - 'message'?: string | null; + 'message': string; static readonly discriminator: string | undefined = undefined; diff --git a/src/v2/generated/models/AuthorizationErrors.ts b/src/v2/generated/models/AuthorizationErrors.ts index dd3f047..9fbc118 100644 --- a/src/v2/generated/models/AuthorizationErrors.ts +++ b/src/v2/generated/models/AuthorizationErrors.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co @@ -20,7 +20,7 @@ export class AuthorizationErrors { /** * AuthorizationError errors */ - 'errors'?: Array | null; + 'errors': Array; static readonly discriminator: string | undefined = undefined; diff --git a/src/v2/generated/models/ChatMessage.ts b/src/v2/generated/models/ChatMessage.ts index 57a9e9e..ad00779 100644 --- a/src/v2/generated/models/ChatMessage.ts +++ b/src/v2/generated/models/ChatMessage.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co @@ -17,7 +17,7 @@ export class ChatMessage { /** * The type of interaction */ - 'type': ChatMessageTypeEnum; + 'type': string; /** * The chat message\'s unique identifier */ @@ -44,7 +44,7 @@ export class ChatMessage { { "name": "type", "baseName": "type", - "type": "ChatMessageTypeEnum", + "type": "string", "format": "" }, { @@ -86,9 +86,6 @@ export class ChatMessage { } } -export enum ChatMessageTypeEnum { - ChatMessage = 'chat-message' -} export enum ChatMessageDirectionEnum { Received = 'received', Sent = 'sent' diff --git a/src/v2/generated/models/CompaniesValue.ts b/src/v2/generated/models/CompaniesValue.ts index 3bb94f7..bee377d 100644 --- a/src/v2/generated/models/CompaniesValue.ts +++ b/src/v2/generated/models/CompaniesValue.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co @@ -17,11 +17,11 @@ export class CompaniesValue { /** * The type of value */ - 'type': CompaniesValueTypeEnum; + 'type': string; /** * The values for many companies */ - 'data': Array | null; + 'data': Array; static readonly discriminator: string | undefined = undefined; @@ -31,7 +31,7 @@ export class CompaniesValue { { "name": "type", "baseName": "type", - "type": "CompaniesValueTypeEnum", + "type": "string", "format": "" }, { @@ -48,8 +48,3 @@ export class CompaniesValue { public constructor() { } } - -export enum CompaniesValueTypeEnum { - CompanyMulti = 'company-multi' -} - diff --git a/src/v2/generated/models/Company.ts b/src/v2/generated/models/Company.ts index 729450b..17be6a2 100644 --- a/src/v2/generated/models/Company.ts +++ b/src/v2/generated/models/Company.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co diff --git a/src/v2/generated/models/CompanyData.ts b/src/v2/generated/models/CompanyData.ts index 9963028..3e381d0 100644 --- a/src/v2/generated/models/CompanyData.ts +++ b/src/v2/generated/models/CompanyData.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co diff --git a/src/v2/generated/models/CompanyListEntry.ts b/src/v2/generated/models/CompanyListEntry.ts index b73ef76..444fa01 100644 --- a/src/v2/generated/models/CompanyListEntry.ts +++ b/src/v2/generated/models/CompanyListEntry.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co @@ -21,7 +21,7 @@ export class CompanyListEntry { /** * The entity type for this list entry */ - 'type': CompanyListEntryTypeEnum; + 'type': string; /** * The date that the list entry was created */ @@ -46,7 +46,7 @@ export class CompanyListEntry { { "name": "type", "baseName": "type", - "type": "CompanyListEntryTypeEnum", + "type": "string", "format": "" }, { @@ -75,8 +75,3 @@ export class CompanyListEntry { public constructor() { } } - -export enum CompanyListEntryTypeEnum { - Company = 'company' -} - diff --git a/src/v2/generated/models/CompanyPaged.ts b/src/v2/generated/models/CompanyPaged.ts index 53d6640..0336cec 100644 --- a/src/v2/generated/models/CompanyPaged.ts +++ b/src/v2/generated/models/CompanyPaged.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co diff --git a/src/v2/generated/models/CompanyValue.ts b/src/v2/generated/models/CompanyValue.ts index da6ae9a..aaa1fa8 100644 --- a/src/v2/generated/models/CompanyValue.ts +++ b/src/v2/generated/models/CompanyValue.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co @@ -17,7 +17,7 @@ export class CompanyValue { /** * The type of value */ - 'type': CompanyValueTypeEnum; + 'type': string; 'data': CompanyData | null; static readonly discriminator: string | undefined = undefined; @@ -28,7 +28,7 @@ export class CompanyValue { { "name": "type", "baseName": "type", - "type": "CompanyValueTypeEnum", + "type": "string", "format": "" }, { @@ -45,8 +45,3 @@ export class CompanyValue { public constructor() { } } - -export enum CompanyValueTypeEnum { - Company = 'company' -} - diff --git a/src/v2/generated/models/ConflictError.ts b/src/v2/generated/models/ConflictError.ts deleted file mode 100644 index 2113fe6..0000000 --- a/src/v2/generated/models/ConflictError.ts +++ /dev/null @@ -1,49 +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 ## 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: 2.0.0 - * 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 ConflictError { - /** - * Error code - */ - 'code'?: string | null; - /** - * Error message - */ - 'message'?: 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": "code", - "baseName": "code", - "type": "string", - "format": "" - }, - { - "name": "message", - "baseName": "message", - "type": "string", - "format": "" - } ]; - - static getAttributeTypeMap() { - return ConflictError.attributeTypeMap; - } - - public constructor() { - } -} diff --git a/src/v2/generated/models/DateValue.ts b/src/v2/generated/models/DateValue.ts index b9e6545..498cd5b 100644 --- a/src/v2/generated/models/DateValue.ts +++ b/src/v2/generated/models/DateValue.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co @@ -16,7 +16,7 @@ export class DateValue { /** * The type of value */ - 'type': DateValueTypeEnum; + 'type': string; /** * The value for a date */ @@ -30,7 +30,7 @@ export class DateValue { { "name": "type", "baseName": "type", - "type": "DateValueTypeEnum", + "type": "string", "format": "" }, { @@ -47,8 +47,3 @@ export class DateValue { public constructor() { } } - -export enum DateValueTypeEnum { - Datetime = 'datetime' -} - diff --git a/src/v2/generated/models/Dropdown.ts b/src/v2/generated/models/Dropdown.ts index 447983b..ba98219 100644 --- a/src/v2/generated/models/Dropdown.ts +++ b/src/v2/generated/models/Dropdown.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co diff --git a/src/v2/generated/models/DropdownValue.ts b/src/v2/generated/models/DropdownValue.ts index d46cf48..8d0e70a 100644 --- a/src/v2/generated/models/DropdownValue.ts +++ b/src/v2/generated/models/DropdownValue.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co @@ -17,7 +17,7 @@ export class DropdownValue { /** * The type of value */ - 'type': DropdownValueTypeEnum; + 'type': string; 'data': Dropdown | null; static readonly discriminator: string | undefined = undefined; @@ -28,7 +28,7 @@ export class DropdownValue { { "name": "type", "baseName": "type", - "type": "DropdownValueTypeEnum", + "type": "string", "format": "" }, { @@ -45,8 +45,3 @@ export class DropdownValue { public constructor() { } } - -export enum DropdownValueTypeEnum { - Dropdown = 'dropdown' -} - diff --git a/src/v2/generated/models/DropdownsValue.ts b/src/v2/generated/models/DropdownsValue.ts index 2430f5e..d053373 100644 --- a/src/v2/generated/models/DropdownsValue.ts +++ b/src/v2/generated/models/DropdownsValue.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co @@ -17,11 +17,11 @@ export class DropdownsValue { /** * The type of value */ - 'type': DropdownsValueTypeEnum; + 'type': string; /** * The value for many dropdown items */ - 'data': Array | null; + 'data': Array; static readonly discriminator: string | undefined = undefined; @@ -31,7 +31,7 @@ export class DropdownsValue { { "name": "type", "baseName": "type", - "type": "DropdownsValueTypeEnum", + "type": "string", "format": "" }, { @@ -48,8 +48,3 @@ export class DropdownsValue { public constructor() { } } - -export enum DropdownsValueTypeEnum { - DropdownMulti = 'dropdown-multi' -} - diff --git a/src/v2/generated/models/Email.ts b/src/v2/generated/models/Email.ts index 3a711b3..37653e1 100644 --- a/src/v2/generated/models/Email.ts +++ b/src/v2/generated/models/Email.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co @@ -17,7 +17,7 @@ export class Email { /** * The type of interaction */ - 'type': EmailTypeEnum; + 'type': string; /** * The email\'s unique identifier */ @@ -30,7 +30,7 @@ export class Email { * The time the email was sent */ 'sentAt': Date; - 'from': Attendee; + '_from': Attendee; /** * The recipients of the email */ @@ -48,7 +48,7 @@ export class Email { { "name": "type", "baseName": "type", - "type": "EmailTypeEnum", + "type": "string", "format": "" }, { @@ -70,7 +70,7 @@ export class Email { "format": "date-time" }, { - "name": "from", + "name": "_from", "baseName": "from", "type": "Attendee", "format": "" @@ -95,8 +95,3 @@ export class Email { public constructor() { } } - -export enum EmailTypeEnum { - Email = 'email' -} - diff --git a/src/v2/generated/models/EmptyMessageBodyError.ts b/src/v2/generated/models/EmptyMessageBodyError.ts deleted file mode 100644 index f908260..0000000 --- a/src/v2/generated/models/EmptyMessageBodyError.ts +++ /dev/null @@ -1,49 +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 ## 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: 2.0.0 - * 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 EmptyMessageBodyError { - /** - * Error code - */ - 'code'?: string | null; - /** - * Error message - */ - 'message'?: 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": "code", - "baseName": "code", - "type": "string", - "format": "" - }, - { - "name": "message", - "baseName": "message", - "type": "string", - "format": "" - } ]; - - static getAttributeTypeMap() { - return EmptyMessageBodyError.attributeTypeMap; - } - - public constructor() { - } -} diff --git a/src/v2/generated/models/Errors.ts b/src/v2/generated/models/Errors.ts deleted file mode 100644 index dd05ff9..0000000 --- a/src/v2/generated/models/Errors.ts +++ /dev/null @@ -1,39 +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 ## 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: 2.0.0 - * 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 Errors { - /** - * Errors - */ - 'errors'?: Array | 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": "errors", - "baseName": "errors", - "type": "Array", - "format": "" - } ]; - - static getAttributeTypeMap() { - return Errors.attributeTypeMap; - } - - public constructor() { - } -} diff --git a/src/v2/generated/models/Field.ts b/src/v2/generated/models/Field.ts index 29ef0d4..7aaff1c 100644 --- a/src/v2/generated/models/Field.ts +++ b/src/v2/generated/models/Field.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co diff --git a/src/v2/generated/models/FieldMetadata.ts b/src/v2/generated/models/FieldMetadata.ts index 59e9e23..f81ec0f 100644 --- a/src/v2/generated/models/FieldMetadata.ts +++ b/src/v2/generated/models/FieldMetadata.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co diff --git a/src/v2/generated/models/FieldMetadataPaged.ts b/src/v2/generated/models/FieldMetadataPaged.ts index 267ae31..f9186e9 100644 --- a/src/v2/generated/models/FieldMetadataPaged.ts +++ b/src/v2/generated/models/FieldMetadataPaged.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co diff --git a/src/v2/generated/models/FieldValue.ts b/src/v2/generated/models/FieldValue.ts index 3a3a9ca..c0f8035 100644 --- a/src/v2/generated/models/FieldValue.ts +++ b/src/v2/generated/models/FieldValue.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co diff --git a/src/v2/generated/models/FloatValue.ts b/src/v2/generated/models/FloatValue.ts index d3be36e..19d53b9 100644 --- a/src/v2/generated/models/FloatValue.ts +++ b/src/v2/generated/models/FloatValue.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co @@ -16,7 +16,7 @@ export class FloatValue { /** * The type of value */ - 'type': FloatValueTypeEnum; + 'type': string; /** * The value for a number */ @@ -30,7 +30,7 @@ export class FloatValue { { "name": "type", "baseName": "type", - "type": "FloatValueTypeEnum", + "type": "string", "format": "" }, { @@ -47,8 +47,3 @@ export class FloatValue { public constructor() { } } - -export enum FloatValueTypeEnum { - Number = 'number' -} - diff --git a/src/v2/generated/models/FloatsValue.ts b/src/v2/generated/models/FloatsValue.ts index 8c2d9c7..a5d8850 100644 --- a/src/v2/generated/models/FloatsValue.ts +++ b/src/v2/generated/models/FloatsValue.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co @@ -16,11 +16,11 @@ export class FloatsValue { /** * The type of value */ - 'type': FloatsValueTypeEnum; + 'type': string; /** * The value for many numbers */ - 'data': Array | null; + 'data': Array; static readonly discriminator: string | undefined = undefined; @@ -30,7 +30,7 @@ export class FloatsValue { { "name": "type", "baseName": "type", - "type": "FloatsValueTypeEnum", + "type": "string", "format": "" }, { @@ -47,8 +47,3 @@ export class FloatsValue { public constructor() { } } - -export enum FloatsValueTypeEnum { - NumberMulti = 'number-multi' -} - diff --git a/src/v2/generated/models/FormulaNumber.ts b/src/v2/generated/models/FormulaNumber.ts index 02730b0..b8cda0f 100644 --- a/src/v2/generated/models/FormulaNumber.ts +++ b/src/v2/generated/models/FormulaNumber.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co diff --git a/src/v2/generated/models/FormulaValue.ts b/src/v2/generated/models/FormulaValue.ts index 02a114b..21dbf2d 100644 --- a/src/v2/generated/models/FormulaValue.ts +++ b/src/v2/generated/models/FormulaValue.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co @@ -17,7 +17,7 @@ export class FormulaValue { /** * The type of value */ - 'type': FormulaValueTypeEnum; + 'type': string; 'data': FormulaNumber | null; static readonly discriminator: string | undefined = undefined; @@ -28,7 +28,7 @@ export class FormulaValue { { "name": "type", "baseName": "type", - "type": "FormulaValueTypeEnum", + "type": "string", "format": "" }, { @@ -45,8 +45,3 @@ export class FormulaValue { public constructor() { } } - -export enum FormulaValueTypeEnum { - FormulaNumber = 'formula-number' -} - diff --git a/src/v2/generated/models/GenericError.ts b/src/v2/generated/models/GenericError.ts deleted file mode 100644 index a97a70a..0000000 --- a/src/v2/generated/models/GenericError.ts +++ /dev/null @@ -1,49 +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 ## 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: 2.0.0 - * 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 GenericError { - /** - * Error code - */ - 'code'?: string | null; - /** - * Error message - */ - 'message'?: 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": "code", - "baseName": "code", - "type": "string", - "format": "" - }, - { - "name": "message", - "baseName": "message", - "type": "string", - "format": "" - } ]; - - static getAttributeTypeMap() { - return GenericError.attributeTypeMap; - } - - public constructor() { - } -} diff --git a/src/v2/generated/models/Grant.ts b/src/v2/generated/models/Grant.ts index 2287cf5..db2a333 100644 --- a/src/v2/generated/models/Grant.ts +++ b/src/v2/generated/models/Grant.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co @@ -16,7 +16,7 @@ export class Grant { /** * The type of grant used to authenticate */ - 'type': GrantTypeEnum; + 'type': string; /** * The scopes available to the current grant */ @@ -34,7 +34,7 @@ export class Grant { { "name": "type", "baseName": "type", - "type": "GrantTypeEnum", + "type": "string", "format": "" }, { @@ -57,8 +57,3 @@ export class Grant { public constructor() { } } - -export enum GrantTypeEnum { - ApiKey = 'api-key' -} - diff --git a/src/v2/generated/models/Interaction.ts b/src/v2/generated/models/Interaction.ts index c811b26..3c7ad7d 100644 --- a/src/v2/generated/models/Interaction.ts +++ b/src/v2/generated/models/Interaction.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co diff --git a/src/v2/generated/models/InteractionValue.ts b/src/v2/generated/models/InteractionValue.ts index 80a5cda..39c8064 100644 --- a/src/v2/generated/models/InteractionValue.ts +++ b/src/v2/generated/models/InteractionValue.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co @@ -17,7 +17,7 @@ export class InteractionValue { /** * The type of value */ - 'type': InteractionValueTypeEnum; + 'type': string; 'data': Interaction | null; static readonly discriminator: string | undefined = undefined; @@ -28,7 +28,7 @@ export class InteractionValue { { "name": "type", "baseName": "type", - "type": "InteractionValueTypeEnum", + "type": "string", "format": "" }, { @@ -45,8 +45,3 @@ export class InteractionValue { public constructor() { } } - -export enum InteractionValueTypeEnum { - Interaction = 'interaction' -} - diff --git a/src/v2/generated/models/InvalidAcceptHeaderError.ts b/src/v2/generated/models/InvalidAcceptHeaderError.ts deleted file mode 100644 index 508dde2..0000000 --- a/src/v2/generated/models/InvalidAcceptHeaderError.ts +++ /dev/null @@ -1,49 +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 ## 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: 2.0.0 - * 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 InvalidAcceptHeaderError { - /** - * Error code - */ - 'code'?: string | null; - /** - * Error message - */ - 'message'?: 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": "code", - "baseName": "code", - "type": "string", - "format": "" - }, - { - "name": "message", - "baseName": "message", - "type": "string", - "format": "" - } ]; - - static getAttributeTypeMap() { - return InvalidAcceptHeaderError.attributeTypeMap; - } - - public constructor() { - } -} diff --git a/src/v2/generated/models/InvalidMessageBodyError.ts b/src/v2/generated/models/InvalidMessageBodyError.ts deleted file mode 100644 index c4337a2..0000000 --- a/src/v2/generated/models/InvalidMessageBodyError.ts +++ /dev/null @@ -1,49 +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 ## 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: 2.0.0 - * 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 InvalidMessageBodyError { - /** - * Error code - */ - 'code'?: string | null; - /** - * Error message - */ - 'message'?: 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": "code", - "baseName": "code", - "type": "string", - "format": "" - }, - { - "name": "message", - "baseName": "message", - "type": "string", - "format": "" - } ]; - - static getAttributeTypeMap() { - return InvalidMessageBodyError.attributeTypeMap; - } - - public constructor() { - } -} diff --git a/src/v2/generated/models/InvalidVersionHeaderError.ts b/src/v2/generated/models/InvalidVersionHeaderError.ts deleted file mode 100644 index c0ba9d4..0000000 --- a/src/v2/generated/models/InvalidVersionHeaderError.ts +++ /dev/null @@ -1,49 +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 ## 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: 2.0.0 - * 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 InvalidVersionHeaderError { - /** - * Error code - */ - 'code'?: string | null; - /** - * Error message - */ - 'message'?: 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": "code", - "baseName": "code", - "type": "string", - "format": "" - }, - { - "name": "message", - "baseName": "message", - "type": "string", - "format": "" - } ]; - - static getAttributeTypeMap() { - return InvalidVersionHeaderError.attributeTypeMap; - } - - public constructor() { - } -} diff --git a/src/v2/generated/models/List.ts b/src/v2/generated/models/List.ts index 6cf2460..8702f4f 100644 --- a/src/v2/generated/models/List.ts +++ b/src/v2/generated/models/List.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co diff --git a/src/v2/generated/models/ListEntry.ts b/src/v2/generated/models/ListEntry.ts index 188de9f..92ada12 100644 --- a/src/v2/generated/models/ListEntry.ts +++ b/src/v2/generated/models/ListEntry.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co diff --git a/src/v2/generated/models/ListEntryPaged.ts b/src/v2/generated/models/ListEntryPaged.ts index 8c5aa84..8b3b6cf 100644 --- a/src/v2/generated/models/ListEntryPaged.ts +++ b/src/v2/generated/models/ListEntryPaged.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co diff --git a/src/v2/generated/models/ListEntryWithEntity.ts b/src/v2/generated/models/ListEntryWithEntity.ts index ab86530..35f5520 100644 --- a/src/v2/generated/models/ListEntryWithEntity.ts +++ b/src/v2/generated/models/ListEntryWithEntity.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co diff --git a/src/v2/generated/models/ListEntryWithEntityPaged.ts b/src/v2/generated/models/ListEntryWithEntityPaged.ts index 047d58c..c6afb1f 100644 --- a/src/v2/generated/models/ListEntryWithEntityPaged.ts +++ b/src/v2/generated/models/ListEntryWithEntityPaged.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co @@ -21,7 +21,7 @@ export class ListEntryWithEntityPaged { /** * A page of ListEntryWithEntity results */ - 'data': Array | null; + 'data': Array; 'pagination': Pagination; static readonly discriminator: string | undefined = undefined; diff --git a/src/v2/generated/models/ListPaged.ts b/src/v2/generated/models/ListPaged.ts index 28e21cb..87d880a 100644 --- a/src/v2/generated/models/ListPaged.ts +++ b/src/v2/generated/models/ListPaged.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co diff --git a/src/v2/generated/models/ListWithType.ts b/src/v2/generated/models/ListWithType.ts index 9a0b1ac..723ee5f 100644 --- a/src/v2/generated/models/ListWithType.ts +++ b/src/v2/generated/models/ListWithType.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co diff --git a/src/v2/generated/models/ListWithTypePaged.ts b/src/v2/generated/models/ListWithTypePaged.ts index 25d917a..e3a9c3d 100644 --- a/src/v2/generated/models/ListWithTypePaged.ts +++ b/src/v2/generated/models/ListWithTypePaged.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co diff --git a/src/v2/generated/models/Location.ts b/src/v2/generated/models/Location.ts index 8a33a3d..1991295 100644 --- a/src/v2/generated/models/Location.ts +++ b/src/v2/generated/models/Location.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co diff --git a/src/v2/generated/models/LocationValue.ts b/src/v2/generated/models/LocationValue.ts index 1b2276c..e5a9a37 100644 --- a/src/v2/generated/models/LocationValue.ts +++ b/src/v2/generated/models/LocationValue.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co @@ -17,7 +17,7 @@ export class LocationValue { /** * The type of value */ - 'type': LocationValueTypeEnum; + 'type': string; 'data': Location | null; static readonly discriminator: string | undefined = undefined; @@ -28,7 +28,7 @@ export class LocationValue { { "name": "type", "baseName": "type", - "type": "LocationValueTypeEnum", + "type": "string", "format": "" }, { @@ -45,8 +45,3 @@ export class LocationValue { public constructor() { } } - -export enum LocationValueTypeEnum { - Location = 'location' -} - diff --git a/src/v2/generated/models/LocationsValue.ts b/src/v2/generated/models/LocationsValue.ts index b1f9515..a0cbff1 100644 --- a/src/v2/generated/models/LocationsValue.ts +++ b/src/v2/generated/models/LocationsValue.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co @@ -17,11 +17,11 @@ export class LocationsValue { /** * The type of value */ - 'type': LocationsValueTypeEnum; + 'type': string; /** * The values for many locations */ - 'data': Array | null; + 'data': Array; static readonly discriminator: string | undefined = undefined; @@ -31,7 +31,7 @@ export class LocationsValue { { "name": "type", "baseName": "type", - "type": "LocationsValueTypeEnum", + "type": "string", "format": "" }, { @@ -48,8 +48,3 @@ export class LocationsValue { public constructor() { } } - -export enum LocationsValueTypeEnum { - LocationMulti = 'location-multi' -} - diff --git a/src/v2/generated/models/Meeting.ts b/src/v2/generated/models/Meeting.ts index 5359c8a..b52d2e9 100644 --- a/src/v2/generated/models/Meeting.ts +++ b/src/v2/generated/models/Meeting.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co @@ -17,7 +17,7 @@ export class Meeting { /** * The type of interaction */ - 'type': MeetingTypeEnum; + 'type': string; /** * The meeting\'s unique identifier */ @@ -51,7 +51,7 @@ export class Meeting { { "name": "type", "baseName": "type", - "type": "MeetingTypeEnum", + "type": "string", "format": "" }, { @@ -98,8 +98,3 @@ 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 deleted file mode 100644 index 4dd3592..0000000 --- a/src/v2/generated/models/MethodNotAllowedError.ts +++ /dev/null @@ -1,49 +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 ## 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: 2.0.0 - * 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 MethodNotAllowedError { - /** - * Error code - */ - 'code'?: string | null; - /** - * Error message - */ - 'message'?: 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": "code", - "baseName": "code", - "type": "string", - "format": "" - }, - { - "name": "message", - "baseName": "message", - "type": "string", - "format": "" - } ]; - - static getAttributeTypeMap() { - return MethodNotAllowedError.attributeTypeMap; - } - - public constructor() { - } -} diff --git a/src/v2/generated/models/ModelError.ts b/src/v2/generated/models/ModelError.ts deleted file mode 100644 index 592803c..0000000 --- a/src/v2/generated/models/ModelError.ts +++ /dev/null @@ -1,72 +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 ## 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: 2.0.0 - * 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 { AuthenticationError } from '../models/AuthenticationError.ts'; -import { AuthorizationError } from '../models/AuthorizationError.ts'; -import { ConflictError } from '../models/ConflictError.ts'; -import { EmptyMessageBodyError } from '../models/EmptyMessageBodyError.ts'; -import { GenericError } from '../models/GenericError.ts'; -import { InvalidAcceptHeaderError } from '../models/InvalidAcceptHeaderError.ts'; -import { InvalidMessageBodyError } from '../models/InvalidMessageBodyError.ts'; -import { InvalidVersionHeaderError } from '../models/InvalidVersionHeaderError.ts'; -import { MethodNotAllowedError } from '../models/MethodNotAllowedError.ts'; -import { NotFoundError } from '../models/NotFoundError.ts'; -import { RateLimitError } from '../models/RateLimitError.ts'; -import { ServerError } from '../models/ServerError.ts'; -import { TooManyMultipartFilesError } from '../models/TooManyMultipartFilesError.ts'; -import { ValidationError } from '../models/ValidationError.ts'; -import { HttpFile } from '../http/http.ts'; - -/** - * @type ModelError - * Type - * @export - */ -export type ModelError = AuthenticationError | AuthorizationError | ConflictError | EmptyMessageBodyError | GenericError | InvalidAcceptHeaderError | InvalidMessageBodyError | InvalidVersionHeaderError | MethodNotAllowedError | NotFoundError | RateLimitError | ServerError | TooManyMultipartFilesError | ValidationError; - -/** -* @type ModelErrorClass -* @export -*/ -export class ModelErrorClass { - static readonly discriminator: string | undefined = "code"; - - static readonly mapping: {[index: string]: string} | undefined = { - "authentication": "AuthenticationError", - "authorization": "AuthorizationError", - "conflict": "ConflictError", - "empty-message-body": "EmptyMessageBodyError", - "error": "GenericError", - "invalid-accept-header": "InvalidAcceptHeaderError", - "invalid-message-body": "InvalidMessageBodyError", - "invalid-version-header": "InvalidVersionHeaderError", - "method-not-allowed": "MethodNotAllowedError", - "not-found": "NotFoundError", - "rate-limit": "RateLimitError", - "server": "ServerError", - "too-many-multipart-files": "TooManyMultipartFilesError", - "validation": "ValidationError", - }; -} - - - - - - - - - - - - - diff --git a/src/v2/generated/models/NotFoundError.ts b/src/v2/generated/models/NotFoundError.ts index 25c81ef..72f82e1 100644 --- a/src/v2/generated/models/NotFoundError.ts +++ b/src/v2/generated/models/NotFoundError.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co @@ -16,11 +16,11 @@ export class NotFoundError { /** * Error code */ - 'code'?: string | null; + 'code': string; /** * Error message */ - 'message'?: string | null; + 'message': string; static readonly discriminator: string | undefined = undefined; diff --git a/src/v2/generated/models/NotFoundErrors.ts b/src/v2/generated/models/NotFoundErrors.ts index 3b995191..8aba256 100644 --- a/src/v2/generated/models/NotFoundErrors.ts +++ b/src/v2/generated/models/NotFoundErrors.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co @@ -20,7 +20,7 @@ export class NotFoundErrors { /** * NotFoundError errors */ - 'errors'?: Array | null; + 'errors': Array; static readonly discriminator: string | undefined = undefined; diff --git a/src/v2/generated/models/ObjectSerializer.ts b/src/v2/generated/models/ObjectSerializer.ts index e16e566..194a6eb 100644 --- a/src/v2/generated/models/ObjectSerializer.ts +++ b/src/v2/generated/models/ObjectSerializer.ts @@ -10,14 +10,11 @@ export * from '../models/CompanyData.ts'; export * from '../models/CompanyListEntry.ts'; export * from '../models/CompanyPaged.ts'; export * from '../models/CompanyValue.ts'; -export * from '../models/ConflictError.ts'; export * from '../models/DateValue.ts'; export * from '../models/Dropdown.ts'; export * from '../models/DropdownValue.ts'; export * from '../models/DropdownsValue.ts'; export * from '../models/Email.ts'; -export * from '../models/EmptyMessageBodyError.ts'; -export * from '../models/Errors.ts'; export * from '../models/Field.ts'; export * from '../models/FieldMetadata.ts'; export * from '../models/FieldMetadataPaged.ts'; @@ -26,13 +23,9 @@ export * from '../models/FloatValue.ts'; export * from '../models/FloatsValue.ts'; export * from '../models/FormulaNumber.ts'; export * from '../models/FormulaValue.ts'; -export * from '../models/GenericError.ts'; export * from '../models/Grant.ts'; export * from '../models/Interaction.ts'; export * from '../models/InteractionValue.ts'; -export * from '../models/InvalidAcceptHeaderError.ts'; -export * from '../models/InvalidMessageBodyError.ts'; -export * from '../models/InvalidVersionHeaderError.ts'; export * from '../models/List.ts'; export * from '../models/ListEntry.ts'; export * from '../models/ListEntryPaged.ts'; @@ -45,8 +38,6 @@ export * from '../models/Location.ts'; export * from '../models/LocationValue.ts'; export * from '../models/LocationsValue.ts'; export * from '../models/Meeting.ts'; -export * from '../models/MethodNotAllowedError.ts'; -export * from '../models/ModelError.ts'; export * from '../models/NotFoundError.ts'; export * from '../models/NotFoundErrors.ts'; export * from '../models/Opportunity.ts'; @@ -63,14 +54,11 @@ export * from '../models/PersonsValue.ts'; export * from '../models/PhoneCall.ts'; export * from '../models/RankedDropdown.ts'; export * from '../models/RankedDropdownValue.ts'; -export * from '../models/RateLimitError.ts'; export * from '../models/SavedView.ts'; export * from '../models/SavedViewPaged.ts'; -export * from '../models/ServerError.ts'; export * from '../models/Tenant.ts'; export * from '../models/TextValue.ts'; export * from '../models/TextsValue.ts'; -export * from '../models/TooManyMultipartFilesError.ts'; export * from '../models/User.ts'; export * from '../models/ValidationError.ts'; export * from '../models/ValidationErrors.ts'; @@ -81,36 +69,29 @@ import { AuthenticationError } from '../models/AuthenticationError.ts'; import { AuthenticationErrors } from '../models/AuthenticationErrors.ts'; import { AuthorizationError } from '../models/AuthorizationError.ts'; import { AuthorizationErrors } from '../models/AuthorizationErrors.ts'; -import { ChatMessage, ChatMessageTypeEnum , ChatMessageDirectionEnum } from '../models/ChatMessage.ts'; -import { CompaniesValue, CompaniesValueTypeEnum } from '../models/CompaniesValue.ts'; +import { ChatMessage , ChatMessageDirectionEnum } from '../models/ChatMessage.ts'; +import { CompaniesValue } from '../models/CompaniesValue.ts'; import { Company } from '../models/Company.ts'; import { CompanyData } from '../models/CompanyData.ts'; -import { CompanyListEntry , CompanyListEntryTypeEnum } from '../models/CompanyListEntry.ts'; +import { CompanyListEntry } from '../models/CompanyListEntry.ts'; import { CompanyPaged } from '../models/CompanyPaged.ts'; -import { CompanyValue, CompanyValueTypeEnum } from '../models/CompanyValue.ts'; -import { ConflictError } from '../models/ConflictError.ts'; -import { DateValue, DateValueTypeEnum } from '../models/DateValue.ts'; +import { CompanyValue } from '../models/CompanyValue.ts'; +import { DateValue } from '../models/DateValue.ts'; import { Dropdown } from '../models/Dropdown.ts'; -import { DropdownValue, DropdownValueTypeEnum } from '../models/DropdownValue.ts'; -import { DropdownsValue, DropdownsValueTypeEnum } from '../models/DropdownsValue.ts'; -import { Email, EmailTypeEnum } from '../models/Email.ts'; -import { EmptyMessageBodyError } from '../models/EmptyMessageBodyError.ts'; -import { Errors } from '../models/Errors.ts'; +import { DropdownValue } from '../models/DropdownValue.ts'; +import { DropdownsValue } from '../models/DropdownsValue.ts'; +import { Email } from '../models/Email.ts'; import { Field , FieldTypeEnum , FieldEnrichmentSourceEnum } from '../models/Field.ts'; import { FieldMetadata , FieldMetadataTypeEnum , FieldMetadataEnrichmentSourceEnum , FieldMetadataValueTypeEnum } from '../models/FieldMetadata.ts'; import { FieldMetadataPaged } from '../models/FieldMetadataPaged.ts'; import { FieldValueClass } from '../models/FieldValue.ts'; -import { FloatValue, FloatValueTypeEnum } from '../models/FloatValue.ts'; -import { FloatsValue, FloatsValueTypeEnum } from '../models/FloatsValue.ts'; +import { FloatValue } from '../models/FloatValue.ts'; +import { FloatsValue } from '../models/FloatsValue.ts'; import { FormulaNumber } from '../models/FormulaNumber.ts'; -import { FormulaValue, FormulaValueTypeEnum } from '../models/FormulaValue.ts'; -import { GenericError } from '../models/GenericError.ts'; -import { Grant, GrantTypeEnum } from '../models/Grant.ts'; +import { FormulaValue } from '../models/FormulaValue.ts'; +import { Grant } from '../models/Grant.ts'; import { InteractionClass } from '../models/Interaction.ts'; -import { InteractionValue, InteractionValueTypeEnum } from '../models/InteractionValue.ts'; -import { InvalidAcceptHeaderError } from '../models/InvalidAcceptHeaderError.ts'; -import { InvalidMessageBodyError } from '../models/InvalidMessageBodyError.ts'; -import { InvalidVersionHeaderError } from '../models/InvalidVersionHeaderError.ts'; +import { InteractionValue } from '../models/InteractionValue.ts'; import { List } from '../models/List.ts'; import { ListEntry } from '../models/ListEntry.ts'; import { ListEntryPaged } from '../models/ListEntryPaged.ts'; @@ -120,35 +101,30 @@ import { ListPaged } from '../models/ListPaged.ts'; import { ListWithType , ListWithTypeTypeEnum } from '../models/ListWithType.ts'; 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, MeetingTypeEnum } from '../models/Meeting.ts'; -import { MethodNotAllowedError } from '../models/MethodNotAllowedError.ts'; -import { ModelErrorClass } from '../models/ModelError.ts'; +import { LocationValue } from '../models/LocationValue.ts'; +import { LocationsValue } from '../models/LocationsValue.ts'; +import { Meeting } from '../models/Meeting.ts'; import { NotFoundError } from '../models/NotFoundError.ts'; import { NotFoundErrors } from '../models/NotFoundErrors.ts'; import { Opportunity } from '../models/Opportunity.ts'; -import { OpportunityListEntry , OpportunityListEntryTypeEnum } from '../models/OpportunityListEntry.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 { Person , PersonTypeEnum } from '../models/Person.ts'; import { PersonData , PersonDataTypeEnum } from '../models/PersonData.ts'; -import { PersonListEntry , PersonListEntryTypeEnum } from '../models/PersonListEntry.ts'; +import { PersonListEntry } from '../models/PersonListEntry.ts'; import { PersonPaged } from '../models/PersonPaged.ts'; -import { PersonValue, PersonValueTypeEnum } from '../models/PersonValue.ts'; -import { PersonsValue, PersonsValueTypeEnum } from '../models/PersonsValue.ts'; -import { PhoneCall, PhoneCallTypeEnum } from '../models/PhoneCall.ts'; +import { PersonValue } from '../models/PersonValue.ts'; +import { PersonsValue } from '../models/PersonsValue.ts'; +import { PhoneCall } from '../models/PhoneCall.ts'; import { RankedDropdown } from '../models/RankedDropdown.ts'; -import { RankedDropdownValue, RankedDropdownValueTypeEnum } from '../models/RankedDropdownValue.ts'; -import { RateLimitError } from '../models/RateLimitError.ts'; +import { RankedDropdownValue } from '../models/RankedDropdownValue.ts'; import { SavedView , SavedViewTypeEnum } from '../models/SavedView.ts'; import { SavedViewPaged } from '../models/SavedViewPaged.ts'; -import { ServerError } from '../models/ServerError.ts'; import { Tenant } from '../models/Tenant.ts'; import { TextValue, TextValueTypeEnum } from '../models/TextValue.ts'; -import { TextsValue, TextsValueTypeEnum } from '../models/TextsValue.ts'; -import { TooManyMultipartFilesError } from '../models/TooManyMultipartFilesError.ts'; +import { TextsValue } from '../models/TextsValue.ts'; import { User } from '../models/User.ts'; import { ValidationError } from '../models/ValidationError.ts'; import { ValidationErrors } from '../models/ValidationErrors.ts'; @@ -167,44 +143,21 @@ let primitives = [ ]; let enumsMap: Set = new Set([ - "ChatMessageTypeEnum", "ChatMessageDirectionEnum", - "CompaniesValueTypeEnum", - "CompanyListEntryTypeEnum", - "CompanyValueTypeEnum", - "DateValueTypeEnum", - "DropdownValueTypeEnum", - "DropdownsValueTypeEnum", - "EmailTypeEnum", "FieldTypeEnum", "FieldEnrichmentSourceEnum", "FieldMetadataTypeEnum", "FieldMetadataEnrichmentSourceEnum", "FieldMetadataValueTypeEnum", "FieldValueTypeEnum", - "FloatValueTypeEnum", - "FloatsValueTypeEnum", - "FormulaValueTypeEnum", - "GrantTypeEnum", "InteractionTypeEnum", "InteractionDirectionEnum", - "InteractionValueTypeEnum", "ListEntryWithEntityTypeEnum", "ListWithTypeTypeEnum", - "LocationValueTypeEnum", - "LocationsValueTypeEnum", - "MeetingTypeEnum", - "OpportunityListEntryTypeEnum", "PersonTypeEnum", "PersonDataTypeEnum", - "PersonListEntryTypeEnum", - "PersonValueTypeEnum", - "PersonsValueTypeEnum", - "PhoneCallTypeEnum", - "RankedDropdownValueTypeEnum", "SavedViewTypeEnum", "TextValueTypeEnum", - "TextsValueTypeEnum", ]); let typeMap: {[index: string]: any} = { @@ -220,14 +173,11 @@ let typeMap: {[index: string]: any} = { "CompanyListEntry": CompanyListEntry, "CompanyPaged": CompanyPaged, "CompanyValue": CompanyValue, - "ConflictError": ConflictError, "DateValue": DateValue, "Dropdown": Dropdown, "DropdownValue": DropdownValue, "DropdownsValue": DropdownsValue, "Email": Email, - "EmptyMessageBodyError": EmptyMessageBodyError, - "Errors": Errors, "Field": Field, "FieldMetadata": FieldMetadata, "FieldMetadataPaged": FieldMetadataPaged, @@ -236,13 +186,9 @@ let typeMap: {[index: string]: any} = { "FloatsValue": FloatsValue, "FormulaNumber": FormulaNumber, "FormulaValue": FormulaValue, - "GenericError": GenericError, "Grant": Grant, "Interaction": InteractionClass, "InteractionValue": InteractionValue, - "InvalidAcceptHeaderError": InvalidAcceptHeaderError, - "InvalidMessageBodyError": InvalidMessageBodyError, - "InvalidVersionHeaderError": InvalidVersionHeaderError, "List": List, "ListEntry": ListEntry, "ListEntryPaged": ListEntryPaged, @@ -255,8 +201,6 @@ let typeMap: {[index: string]: any} = { "LocationValue": LocationValue, "LocationsValue": LocationsValue, "Meeting": Meeting, - "MethodNotAllowedError": MethodNotAllowedError, - "ModelError": ModelErrorClass, "NotFoundError": NotFoundError, "NotFoundErrors": NotFoundErrors, "Opportunity": Opportunity, @@ -273,14 +217,11 @@ let typeMap: {[index: string]: any} = { "PhoneCall": PhoneCall, "RankedDropdown": RankedDropdown, "RankedDropdownValue": RankedDropdownValue, - "RateLimitError": RateLimitError, "SavedView": SavedView, "SavedViewPaged": SavedViewPaged, - "ServerError": ServerError, "Tenant": Tenant, "TextValue": TextValue, "TextsValue": TextsValue, - "TooManyMultipartFilesError": TooManyMultipartFilesError, "User": User, "ValidationError": ValidationError, "ValidationErrors": ValidationErrors, diff --git a/src/v2/generated/models/Opportunity.ts b/src/v2/generated/models/Opportunity.ts index cad6782..8ff75ff 100644 --- a/src/v2/generated/models/Opportunity.ts +++ b/src/v2/generated/models/Opportunity.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co diff --git a/src/v2/generated/models/OpportunityListEntry.ts b/src/v2/generated/models/OpportunityListEntry.ts index 14f01d1..ef356d0 100644 --- a/src/v2/generated/models/OpportunityListEntry.ts +++ b/src/v2/generated/models/OpportunityListEntry.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co @@ -21,7 +21,7 @@ export class OpportunityListEntry { /** * The entity type for this list entry */ - 'type': OpportunityListEntryTypeEnum; + 'type': string; /** * The date that the list entry was created */ @@ -46,7 +46,7 @@ export class OpportunityListEntry { { "name": "type", "baseName": "type", - "type": "OpportunityListEntryTypeEnum", + "type": "string", "format": "" }, { @@ -75,8 +75,3 @@ export class OpportunityListEntry { public constructor() { } } - -export enum OpportunityListEntryTypeEnum { - Opportunity = 'opportunity' -} - diff --git a/src/v2/generated/models/OpportunityPaged.ts b/src/v2/generated/models/OpportunityPaged.ts index 58e0cc3..38452d3 100644 --- a/src/v2/generated/models/OpportunityPaged.ts +++ b/src/v2/generated/models/OpportunityPaged.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co diff --git a/src/v2/generated/models/OpportunityWithFields.ts b/src/v2/generated/models/OpportunityWithFields.ts index 31d8abc..36babc0 100644 --- a/src/v2/generated/models/OpportunityWithFields.ts +++ b/src/v2/generated/models/OpportunityWithFields.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co diff --git a/src/v2/generated/models/Pagination.ts b/src/v2/generated/models/Pagination.ts index 0f63a82..a201090 100644 --- a/src/v2/generated/models/Pagination.ts +++ b/src/v2/generated/models/Pagination.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co diff --git a/src/v2/generated/models/Person.ts b/src/v2/generated/models/Person.ts index 587cf82..bbe8c41 100644 --- a/src/v2/generated/models/Person.ts +++ b/src/v2/generated/models/Person.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co diff --git a/src/v2/generated/models/PersonData.ts b/src/v2/generated/models/PersonData.ts index 81f8c26..a9d3552 100644 --- a/src/v2/generated/models/PersonData.ts +++ b/src/v2/generated/models/PersonData.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co diff --git a/src/v2/generated/models/PersonListEntry.ts b/src/v2/generated/models/PersonListEntry.ts index f9281e3..52b033f 100644 --- a/src/v2/generated/models/PersonListEntry.ts +++ b/src/v2/generated/models/PersonListEntry.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co @@ -21,7 +21,7 @@ export class PersonListEntry { /** * The entity type for this list entry */ - 'type': PersonListEntryTypeEnum; + 'type': string; /** * The date that the list entry was created */ @@ -46,7 +46,7 @@ export class PersonListEntry { { "name": "type", "baseName": "type", - "type": "PersonListEntryTypeEnum", + "type": "string", "format": "" }, { @@ -75,8 +75,3 @@ export class PersonListEntry { public constructor() { } } - -export enum PersonListEntryTypeEnum { - Person = 'person' -} - diff --git a/src/v2/generated/models/PersonPaged.ts b/src/v2/generated/models/PersonPaged.ts index 42aadc3..0c8b13f 100644 --- a/src/v2/generated/models/PersonPaged.ts +++ b/src/v2/generated/models/PersonPaged.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co diff --git a/src/v2/generated/models/PersonValue.ts b/src/v2/generated/models/PersonValue.ts index cefd953..a1d2a54 100644 --- a/src/v2/generated/models/PersonValue.ts +++ b/src/v2/generated/models/PersonValue.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co @@ -17,7 +17,7 @@ export class PersonValue { /** * The type of value */ - 'type': PersonValueTypeEnum; + 'type': string; 'data': PersonData | null; static readonly discriminator: string | undefined = undefined; @@ -28,7 +28,7 @@ export class PersonValue { { "name": "type", "baseName": "type", - "type": "PersonValueTypeEnum", + "type": "string", "format": "" }, { @@ -45,8 +45,3 @@ export class PersonValue { public constructor() { } } - -export enum PersonValueTypeEnum { - Person = 'person' -} - diff --git a/src/v2/generated/models/PersonsValue.ts b/src/v2/generated/models/PersonsValue.ts index efb40a7..71ef10d 100644 --- a/src/v2/generated/models/PersonsValue.ts +++ b/src/v2/generated/models/PersonsValue.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co @@ -17,11 +17,11 @@ export class PersonsValue { /** * The type of value */ - 'type': PersonsValueTypeEnum; + 'type': string; /** * The values for many persons */ - 'data': Array | null; + 'data': Array; static readonly discriminator: string | undefined = undefined; @@ -31,7 +31,7 @@ export class PersonsValue { { "name": "type", "baseName": "type", - "type": "PersonsValueTypeEnum", + "type": "string", "format": "" }, { @@ -48,8 +48,3 @@ export class PersonsValue { public constructor() { } } - -export enum PersonsValueTypeEnum { - PersonMulti = 'person-multi' -} - diff --git a/src/v2/generated/models/PhoneCall.ts b/src/v2/generated/models/PhoneCall.ts index e405470..8d4a492 100644 --- a/src/v2/generated/models/PhoneCall.ts +++ b/src/v2/generated/models/PhoneCall.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co @@ -17,7 +17,7 @@ export class PhoneCall { /** * The type of interaction */ - 'type': PhoneCallTypeEnum; + 'type': string; /** * The phon_call\'s unique identifier */ @@ -39,7 +39,7 @@ export class PhoneCall { { "name": "type", "baseName": "type", - "type": "PhoneCallTypeEnum", + "type": "string", "format": "" }, { @@ -68,8 +68,3 @@ export class PhoneCall { public constructor() { } } - -export enum PhoneCallTypeEnum { - Call = 'call' -} - diff --git a/src/v2/generated/models/RankedDropdown.ts b/src/v2/generated/models/RankedDropdown.ts index 8f3161e..601e5ca 100644 --- a/src/v2/generated/models/RankedDropdown.ts +++ b/src/v2/generated/models/RankedDropdown.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co diff --git a/src/v2/generated/models/RankedDropdownValue.ts b/src/v2/generated/models/RankedDropdownValue.ts index fd038df..16e7a25 100644 --- a/src/v2/generated/models/RankedDropdownValue.ts +++ b/src/v2/generated/models/RankedDropdownValue.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co @@ -17,7 +17,7 @@ export class RankedDropdownValue { /** * The type of value */ - 'type': RankedDropdownValueTypeEnum; + 'type': string; 'data': RankedDropdown | null; static readonly discriminator: string | undefined = undefined; @@ -28,7 +28,7 @@ export class RankedDropdownValue { { "name": "type", "baseName": "type", - "type": "RankedDropdownValueTypeEnum", + "type": "string", "format": "" }, { @@ -45,8 +45,3 @@ export class RankedDropdownValue { public constructor() { } } - -export enum RankedDropdownValueTypeEnum { - RankedDropdown = 'ranked-dropdown' -} - diff --git a/src/v2/generated/models/RateLimitError.ts b/src/v2/generated/models/RateLimitError.ts deleted file mode 100644 index 0fcd615..0000000 --- a/src/v2/generated/models/RateLimitError.ts +++ /dev/null @@ -1,49 +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 ## 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: 2.0.0 - * 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 RateLimitError { - /** - * Error code - */ - 'code'?: string | null; - /** - * Error message - */ - 'message'?: 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": "code", - "baseName": "code", - "type": "string", - "format": "" - }, - { - "name": "message", - "baseName": "message", - "type": "string", - "format": "" - } ]; - - static getAttributeTypeMap() { - return RateLimitError.attributeTypeMap; - } - - public constructor() { - } -} diff --git a/src/v2/generated/models/SavedView.ts b/src/v2/generated/models/SavedView.ts index 2c72d98..9893b71 100644 --- a/src/v2/generated/models/SavedView.ts +++ b/src/v2/generated/models/SavedView.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co diff --git a/src/v2/generated/models/SavedViewPaged.ts b/src/v2/generated/models/SavedViewPaged.ts index c6dd455..7bb39a6 100644 --- a/src/v2/generated/models/SavedViewPaged.ts +++ b/src/v2/generated/models/SavedViewPaged.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co diff --git a/src/v2/generated/models/ServerError.ts b/src/v2/generated/models/ServerError.ts deleted file mode 100644 index bd13722..0000000 --- a/src/v2/generated/models/ServerError.ts +++ /dev/null @@ -1,49 +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 ## 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: 2.0.0 - * 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 ServerError { - /** - * Error code - */ - 'code'?: string | null; - /** - * Error message - */ - 'message'?: 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": "code", - "baseName": "code", - "type": "string", - "format": "" - }, - { - "name": "message", - "baseName": "message", - "type": "string", - "format": "" - } ]; - - static getAttributeTypeMap() { - return ServerError.attributeTypeMap; - } - - public constructor() { - } -} diff --git a/src/v2/generated/models/Tenant.ts b/src/v2/generated/models/Tenant.ts index 51ca803..1f73edd 100644 --- a/src/v2/generated/models/Tenant.ts +++ b/src/v2/generated/models/Tenant.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co diff --git a/src/v2/generated/models/TextValue.ts b/src/v2/generated/models/TextValue.ts index 6836e49..9358199 100644 --- a/src/v2/generated/models/TextValue.ts +++ b/src/v2/generated/models/TextValue.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co diff --git a/src/v2/generated/models/TextsValue.ts b/src/v2/generated/models/TextsValue.ts index d409613..efc1649 100644 --- a/src/v2/generated/models/TextsValue.ts +++ b/src/v2/generated/models/TextsValue.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co @@ -16,11 +16,11 @@ export class TextsValue { /** * The type of value */ - 'type': TextsValueTypeEnum; + 'type': string; /** * The value for many strings */ - 'data': Array | null; + 'data': Array; static readonly discriminator: string | undefined = undefined; @@ -30,7 +30,7 @@ export class TextsValue { { "name": "type", "baseName": "type", - "type": "TextsValueTypeEnum", + "type": "string", "format": "" }, { @@ -47,8 +47,3 @@ export class TextsValue { public constructor() { } } - -export enum TextsValueTypeEnum { - FilterableTextMulti = 'filterable-text-multi' -} - diff --git a/src/v2/generated/models/TooManyMultipartFilesError.ts b/src/v2/generated/models/TooManyMultipartFilesError.ts deleted file mode 100644 index f9ccd38..0000000 --- a/src/v2/generated/models/TooManyMultipartFilesError.ts +++ /dev/null @@ -1,49 +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 ## 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: 2.0.0 - * 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 TooManyMultipartFilesError { - /** - * Error code - */ - 'code'?: string | null; - /** - * Error message - */ - 'message'?: 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": "code", - "baseName": "code", - "type": "string", - "format": "" - }, - { - "name": "message", - "baseName": "message", - "type": "string", - "format": "" - } ]; - - static getAttributeTypeMap() { - return TooManyMultipartFilesError.attributeTypeMap; - } - - public constructor() { - } -} diff --git a/src/v2/generated/models/User.ts b/src/v2/generated/models/User.ts index e5065b6..75c2632 100644 --- a/src/v2/generated/models/User.ts +++ b/src/v2/generated/models/User.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co diff --git a/src/v2/generated/models/ValidationError.ts b/src/v2/generated/models/ValidationError.ts index 019d916..4162e56 100644 --- a/src/v2/generated/models/ValidationError.ts +++ b/src/v2/generated/models/ValidationError.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co @@ -16,15 +16,15 @@ export class ValidationError { /** * Error code */ - 'code'?: string | null; + 'code': string; /** * Error message */ - 'message'?: string | null; + 'message': string; /** * Param the error refers to */ - 'param'?: string | null; + 'param': string; static readonly discriminator: string | undefined = undefined; diff --git a/src/v2/generated/models/ValidationErrors.ts b/src/v2/generated/models/ValidationErrors.ts index 31ff251..f32f197 100644 --- a/src/v2/generated/models/ValidationErrors.ts +++ b/src/v2/generated/models/ValidationErrors.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co @@ -20,7 +20,7 @@ export class ValidationErrors { /** * ValidationError errors */ - 'errors'?: Array | null; + 'errors': Array; static readonly discriminator: string | undefined = undefined; diff --git a/src/v2/generated/models/WhoAmI.ts b/src/v2/generated/models/WhoAmI.ts index 19cdd18..505af1c 100644 --- a/src/v2/generated/models/WhoAmI.ts +++ b/src/v2/generated/models/WhoAmI.ts @@ -1,6 +1,6 @@ /** * 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 ## 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, 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 ## 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: 2.0.0 * Contact: support@affinity.co diff --git a/src/v2/generated/models/all.ts b/src/v2/generated/models/all.ts index bb88ec1..b01e638 100644 --- a/src/v2/generated/models/all.ts +++ b/src/v2/generated/models/all.ts @@ -10,14 +10,11 @@ export * from '../models/CompanyData.ts' export * from '../models/CompanyListEntry.ts' export * from '../models/CompanyPaged.ts' export * from '../models/CompanyValue.ts' -export * from '../models/ConflictError.ts' export * from '../models/DateValue.ts' export * from '../models/Dropdown.ts' export * from '../models/DropdownValue.ts' export * from '../models/DropdownsValue.ts' export * from '../models/Email.ts' -export * from '../models/EmptyMessageBodyError.ts' -export * from '../models/Errors.ts' export * from '../models/Field.ts' export * from '../models/FieldMetadata.ts' export * from '../models/FieldMetadataPaged.ts' @@ -26,13 +23,9 @@ export * from '../models/FloatValue.ts' export * from '../models/FloatsValue.ts' export * from '../models/FormulaNumber.ts' export * from '../models/FormulaValue.ts' -export * from '../models/GenericError.ts' export * from '../models/Grant.ts' export * from '../models/Interaction.ts' export * from '../models/InteractionValue.ts' -export * from '../models/InvalidAcceptHeaderError.ts' -export * from '../models/InvalidMessageBodyError.ts' -export * from '../models/InvalidVersionHeaderError.ts' export * from '../models/List.ts' export * from '../models/ListEntry.ts' export * from '../models/ListEntryPaged.ts' @@ -45,8 +38,6 @@ export * from '../models/Location.ts' export * from '../models/LocationValue.ts' export * from '../models/LocationsValue.ts' export * from '../models/Meeting.ts' -export * from '../models/MethodNotAllowedError.ts' -export * from '../models/ModelError.ts' export * from '../models/NotFoundError.ts' export * from '../models/NotFoundErrors.ts' export * from '../models/Opportunity.ts' @@ -63,14 +54,11 @@ export * from '../models/PersonsValue.ts' export * from '../models/PhoneCall.ts' export * from '../models/RankedDropdown.ts' export * from '../models/RankedDropdownValue.ts' -export * from '../models/RateLimitError.ts' export * from '../models/SavedView.ts' export * from '../models/SavedViewPaged.ts' -export * from '../models/ServerError.ts' export * from '../models/Tenant.ts' export * from '../models/TextValue.ts' export * from '../models/TextsValue.ts' -export * from '../models/TooManyMultipartFilesError.ts' export * from '../models/User.ts' export * from '../models/ValidationError.ts' export * from '../models/ValidationErrors.ts' diff --git a/src/v2/generated/types/ObjectParamAPI.ts b/src/v2/generated/types/ObjectParamAPI.ts index 54218d8..49d5099 100644 --- a/src/v2/generated/types/ObjectParamAPI.ts +++ b/src/v2/generated/types/ObjectParamAPI.ts @@ -13,14 +13,11 @@ import { CompanyData } from '../models/CompanyData.ts'; import { CompanyListEntry } from '../models/CompanyListEntry.ts'; import { CompanyPaged } from '../models/CompanyPaged.ts'; import { CompanyValue } from '../models/CompanyValue.ts'; -import { ConflictError } from '../models/ConflictError.ts'; import { DateValue } from '../models/DateValue.ts'; import { Dropdown } from '../models/Dropdown.ts'; import { DropdownValue } from '../models/DropdownValue.ts'; import { DropdownsValue } from '../models/DropdownsValue.ts'; import { Email } from '../models/Email.ts'; -import { EmptyMessageBodyError } from '../models/EmptyMessageBodyError.ts'; -import { Errors } from '../models/Errors.ts'; import { Field } from '../models/Field.ts'; import { FieldMetadata } from '../models/FieldMetadata.ts'; import { FieldMetadataPaged } from '../models/FieldMetadataPaged.ts'; @@ -29,13 +26,9 @@ import { FloatValue } from '../models/FloatValue.ts'; import { FloatsValue } from '../models/FloatsValue.ts'; import { FormulaNumber } from '../models/FormulaNumber.ts'; import { FormulaValue } from '../models/FormulaValue.ts'; -import { GenericError } from '../models/GenericError.ts'; import { Grant } from '../models/Grant.ts'; import { Interaction } from '../models/Interaction.ts'; import { InteractionValue } from '../models/InteractionValue.ts'; -import { InvalidAcceptHeaderError } from '../models/InvalidAcceptHeaderError.ts'; -import { InvalidMessageBodyError } from '../models/InvalidMessageBodyError.ts'; -import { InvalidVersionHeaderError } from '../models/InvalidVersionHeaderError.ts'; import { List } from '../models/List.ts'; import { ListEntry } from '../models/ListEntry.ts'; import { ListEntryPaged } from '../models/ListEntryPaged.ts'; @@ -48,8 +41,6 @@ import { Location } from '../models/Location.ts'; import { LocationValue } from '../models/LocationValue.ts'; import { LocationsValue } from '../models/LocationsValue.ts'; import { Meeting } from '../models/Meeting.ts'; -import { MethodNotAllowedError } from '../models/MethodNotAllowedError.ts'; -import { ModelError } from '../models/ModelError.ts'; import { NotFoundError } from '../models/NotFoundError.ts'; import { NotFoundErrors } from '../models/NotFoundErrors.ts'; import { Opportunity } from '../models/Opportunity.ts'; @@ -66,14 +57,11 @@ import { PersonsValue } from '../models/PersonsValue.ts'; import { PhoneCall } from '../models/PhoneCall.ts'; import { RankedDropdown } from '../models/RankedDropdown.ts'; import { RankedDropdownValue } from '../models/RankedDropdownValue.ts'; -import { RateLimitError } from '../models/RateLimitError.ts'; import { SavedView } from '../models/SavedView.ts'; import { SavedViewPaged } from '../models/SavedViewPaged.ts'; -import { ServerError } from '../models/ServerError.ts'; import { Tenant } from '../models/Tenant.ts'; import { TextValue } from '../models/TextValue.ts'; import { TextsValue } from '../models/TextsValue.ts'; -import { TooManyMultipartFilesError } from '../models/TooManyMultipartFilesError.ts'; import { User } from '../models/User.ts'; import { ValidationError } from '../models/ValidationError.ts'; import { ValidationErrors } from '../models/ValidationErrors.ts'; diff --git a/src/v2/generated/types/ObservableAPI.ts b/src/v2/generated/types/ObservableAPI.ts index a3f6e8b..3bb42f6 100644 --- a/src/v2/generated/types/ObservableAPI.ts +++ b/src/v2/generated/types/ObservableAPI.ts @@ -14,14 +14,11 @@ import { CompanyData } from '../models/CompanyData.ts'; import { CompanyListEntry } from '../models/CompanyListEntry.ts'; import { CompanyPaged } from '../models/CompanyPaged.ts'; import { CompanyValue } from '../models/CompanyValue.ts'; -import { ConflictError } from '../models/ConflictError.ts'; import { DateValue } from '../models/DateValue.ts'; import { Dropdown } from '../models/Dropdown.ts'; import { DropdownValue } from '../models/DropdownValue.ts'; import { DropdownsValue } from '../models/DropdownsValue.ts'; import { Email } from '../models/Email.ts'; -import { EmptyMessageBodyError } from '../models/EmptyMessageBodyError.ts'; -import { Errors } from '../models/Errors.ts'; import { Field } from '../models/Field.ts'; import { FieldMetadata } from '../models/FieldMetadata.ts'; import { FieldMetadataPaged } from '../models/FieldMetadataPaged.ts'; @@ -30,13 +27,9 @@ import { FloatValue } from '../models/FloatValue.ts'; import { FloatsValue } from '../models/FloatsValue.ts'; import { FormulaNumber } from '../models/FormulaNumber.ts'; import { FormulaValue } from '../models/FormulaValue.ts'; -import { GenericError } from '../models/GenericError.ts'; import { Grant } from '../models/Grant.ts'; import { Interaction } from '../models/Interaction.ts'; import { InteractionValue } from '../models/InteractionValue.ts'; -import { InvalidAcceptHeaderError } from '../models/InvalidAcceptHeaderError.ts'; -import { InvalidMessageBodyError } from '../models/InvalidMessageBodyError.ts'; -import { InvalidVersionHeaderError } from '../models/InvalidVersionHeaderError.ts'; import { List } from '../models/List.ts'; import { ListEntry } from '../models/ListEntry.ts'; import { ListEntryPaged } from '../models/ListEntryPaged.ts'; @@ -49,8 +42,6 @@ import { Location } from '../models/Location.ts'; import { LocationValue } from '../models/LocationValue.ts'; import { LocationsValue } from '../models/LocationsValue.ts'; import { Meeting } from '../models/Meeting.ts'; -import { MethodNotAllowedError } from '../models/MethodNotAllowedError.ts'; -import { ModelError } from '../models/ModelError.ts'; import { NotFoundError } from '../models/NotFoundError.ts'; import { NotFoundErrors } from '../models/NotFoundErrors.ts'; import { Opportunity } from '../models/Opportunity.ts'; @@ -67,14 +58,11 @@ import { PersonsValue } from '../models/PersonsValue.ts'; import { PhoneCall } from '../models/PhoneCall.ts'; import { RankedDropdown } from '../models/RankedDropdown.ts'; import { RankedDropdownValue } from '../models/RankedDropdownValue.ts'; -import { RateLimitError } from '../models/RateLimitError.ts'; import { SavedView } from '../models/SavedView.ts'; import { SavedViewPaged } from '../models/SavedViewPaged.ts'; -import { ServerError } from '../models/ServerError.ts'; import { Tenant } from '../models/Tenant.ts'; import { TextValue } from '../models/TextValue.ts'; import { TextsValue } from '../models/TextsValue.ts'; -import { TooManyMultipartFilesError } from '../models/TooManyMultipartFilesError.ts'; import { User } from '../models/User.ts'; import { ValidationError } from '../models/ValidationError.ts'; import { ValidationErrors } from '../models/ValidationErrors.ts'; diff --git a/src/v2/generated/types/PromiseAPI.ts b/src/v2/generated/types/PromiseAPI.ts index 5c4fa4f..712b0a0 100644 --- a/src/v2/generated/types/PromiseAPI.ts +++ b/src/v2/generated/types/PromiseAPI.ts @@ -13,14 +13,11 @@ import { CompanyData } from '../models/CompanyData.ts'; import { CompanyListEntry } from '../models/CompanyListEntry.ts'; import { CompanyPaged } from '../models/CompanyPaged.ts'; import { CompanyValue } from '../models/CompanyValue.ts'; -import { ConflictError } from '../models/ConflictError.ts'; import { DateValue } from '../models/DateValue.ts'; import { Dropdown } from '../models/Dropdown.ts'; import { DropdownValue } from '../models/DropdownValue.ts'; import { DropdownsValue } from '../models/DropdownsValue.ts'; import { Email } from '../models/Email.ts'; -import { EmptyMessageBodyError } from '../models/EmptyMessageBodyError.ts'; -import { Errors } from '../models/Errors.ts'; import { Field } from '../models/Field.ts'; import { FieldMetadata } from '../models/FieldMetadata.ts'; import { FieldMetadataPaged } from '../models/FieldMetadataPaged.ts'; @@ -29,13 +26,9 @@ import { FloatValue } from '../models/FloatValue.ts'; import { FloatsValue } from '../models/FloatsValue.ts'; import { FormulaNumber } from '../models/FormulaNumber.ts'; import { FormulaValue } from '../models/FormulaValue.ts'; -import { GenericError } from '../models/GenericError.ts'; import { Grant } from '../models/Grant.ts'; import { Interaction } from '../models/Interaction.ts'; import { InteractionValue } from '../models/InteractionValue.ts'; -import { InvalidAcceptHeaderError } from '../models/InvalidAcceptHeaderError.ts'; -import { InvalidMessageBodyError } from '../models/InvalidMessageBodyError.ts'; -import { InvalidVersionHeaderError } from '../models/InvalidVersionHeaderError.ts'; import { List } from '../models/List.ts'; import { ListEntry } from '../models/ListEntry.ts'; import { ListEntryPaged } from '../models/ListEntryPaged.ts'; @@ -48,8 +41,6 @@ import { Location } from '../models/Location.ts'; import { LocationValue } from '../models/LocationValue.ts'; import { LocationsValue } from '../models/LocationsValue.ts'; import { Meeting } from '../models/Meeting.ts'; -import { MethodNotAllowedError } from '../models/MethodNotAllowedError.ts'; -import { ModelError } from '../models/ModelError.ts'; import { NotFoundError } from '../models/NotFoundError.ts'; import { NotFoundErrors } from '../models/NotFoundErrors.ts'; import { Opportunity } from '../models/Opportunity.ts'; @@ -66,14 +57,11 @@ import { PersonsValue } from '../models/PersonsValue.ts'; import { PhoneCall } from '../models/PhoneCall.ts'; import { RankedDropdown } from '../models/RankedDropdown.ts'; import { RankedDropdownValue } from '../models/RankedDropdownValue.ts'; -import { RateLimitError } from '../models/RateLimitError.ts'; import { SavedView } from '../models/SavedView.ts'; import { SavedViewPaged } from '../models/SavedViewPaged.ts'; -import { ServerError } from '../models/ServerError.ts'; import { Tenant } from '../models/Tenant.ts'; import { TextValue } from '../models/TextValue.ts'; import { TextsValue } from '../models/TextsValue.ts'; -import { TooManyMultipartFilesError } from '../models/TooManyMultipartFilesError.ts'; import { User } from '../models/User.ts'; import { ValidationError } from '../models/ValidationError.ts'; import { ValidationErrors } from '../models/ValidationErrors.ts'; From f047f8b0162eb24eb57b62bd5d5e76a022412084 Mon Sep 17 00:00:00 2001 From: Joscha Feth Date: Sat, 28 Sep 2024 23:25:44 +0100 Subject: [PATCH 3/9] re-add errors --- openapi/{2024-09-26.json => 2024-09-28.json} | 202 +++++++++++++++++- src/v2/generated/.openapi-generator/FILES | 8 + src/v2/generated/models/BadRequestError.ts | 49 +++++ src/v2/generated/models/Company.ts | 2 +- src/v2/generated/models/CompanyData.ts | 2 +- src/v2/generated/models/ConflictError.ts | 49 +++++ .../generated/models/MethodNotAllowedError.ts | 49 +++++ src/v2/generated/models/NotAcceptableError.ts | 49 +++++ .../generated/models/NotImplementedError.ts | 49 +++++ src/v2/generated/models/ObjectSerializer.ts | 24 +++ src/v2/generated/models/RateLimitError.ts | 49 +++++ src/v2/generated/models/ServerError.ts | 49 +++++ .../models/UnprocessableEntityError.ts | 49 +++++ src/v2/generated/models/all.ts | 8 + src/v2/generated/types/ObjectParamAPI.ts | 8 + src/v2/generated/types/ObservableAPI.ts | 8 + src/v2/generated/types/PromiseAPI.ts | 8 + 17 files changed, 658 insertions(+), 4 deletions(-) rename openapi/{2024-09-26.json => 2024-09-28.json} (97%) create mode 100644 src/v2/generated/models/BadRequestError.ts create mode 100644 src/v2/generated/models/ConflictError.ts create mode 100644 src/v2/generated/models/MethodNotAllowedError.ts create mode 100644 src/v2/generated/models/NotAcceptableError.ts create mode 100644 src/v2/generated/models/NotImplementedError.ts create mode 100644 src/v2/generated/models/RateLimitError.ts create mode 100644 src/v2/generated/models/ServerError.ts create mode 100644 src/v2/generated/models/UnprocessableEntityError.ts diff --git a/openapi/2024-09-26.json b/openapi/2024-09-28.json similarity index 97% rename from openapi/2024-09-26.json rename to openapi/2024-09-28.json index cdd1c53..10a18ce 100644 --- a/openapi/2024-09-26.json +++ b/openapi/2024-09-28.json @@ -1649,6 +1649,198 @@ } }, "schemas": { + "BadRequestError": { + "examples": [ + { + "code": "bad-request", + "message": "🚨 Error! Sound the alarm! 🚨" + } + ], + "properties": { + "code": { + "description": "Error code", + "const": "bad-request", + "type": "string" + }, + "message": { + "description": "Error message", + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "type": "object" + }, + "ConflictError": { + "examples": [ + { + "code": "conflict", + "message": "🚨 Error! Sound the alarm! 🚨" + } + ], + "properties": { + "code": { + "description": "Error code", + "const": "conflict", + "type": "string" + }, + "message": { + "description": "Error message", + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "type": "object" + }, + "MethodNotAllowedError": { + "examples": [ + { + "code": "method-not-allowed", + "message": "🚨 Error! Sound the alarm! 🚨" + } + ], + "properties": { + "code": { + "description": "Error code", + "const": "method-not-allowed", + "type": "string" + }, + "message": { + "description": "Error message", + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "type": "object" + }, + "NotAcceptableError": { + "examples": [ + { + "code": "not-acceptable", + "message": "🚨 Error! Sound the alarm! 🚨" + } + ], + "properties": { + "code": { + "description": "Error code", + "const": "not-acceptable", + "type": "string" + }, + "message": { + "description": "Error message", + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "type": "object" + }, + "NotImplementedError": { + "examples": [ + { + "code": "not-implemented", + "message": "🚨 Error! Sound the alarm! 🚨" + } + ], + "properties": { + "code": { + "description": "Error code", + "const": "not-implemented", + "type": "string" + }, + "message": { + "description": "Error message", + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "type": "object" + }, + "RateLimitError": { + "examples": [ + { + "code": "rate-limit", + "message": "🚨 Error! Sound the alarm! 🚨" + } + ], + "properties": { + "code": { + "description": "Error code", + "const": "rate-limit", + "type": "string" + }, + "message": { + "description": "Error message", + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "type": "object" + }, + "ServerError": { + "examples": [ + { + "code": "server", + "message": "🚨 Error! Sound the alarm! 🚨" + } + ], + "properties": { + "code": { + "description": "Error code", + "const": "server", + "type": "string" + }, + "message": { + "description": "Error message", + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "type": "object" + }, + "UnprocessableEntityError": { + "examples": [ + { + "code": "unprocessable-entity", + "message": "🚨 Error! Sound the alarm! 🚨" + } + ], + "properties": { + "code": { + "description": "Error code", + "const": "unprocessable-entity", + "type": "string" + }, + "message": { + "description": "Error message", + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "type": "object" + }, "Tenant": { "examples": [ { @@ -1961,7 +2153,10 @@ "acme.co" ], "format": "hostname", - "type": "string" + "type": [ + "string", + "null" + ] } }, "required": [ @@ -3157,7 +3352,10 @@ "acme.co" ], "format": "hostname", - "type": "string" + "type": [ + "string", + "null" + ] }, "domains": { "description": "All of the company's domains", diff --git a/src/v2/generated/.openapi-generator/FILES b/src/v2/generated/.openapi-generator/FILES index b45725e..9c06d1f 100644 --- a/src/v2/generated/.openapi-generator/FILES +++ b/src/v2/generated/.openapi-generator/FILES @@ -24,6 +24,7 @@ models/AuthenticationError.ts models/AuthenticationErrors.ts models/AuthorizationError.ts models/AuthorizationErrors.ts +models/BadRequestError.ts models/ChatMessage.ts models/CompaniesValue.ts models/Company.ts @@ -31,6 +32,7 @@ models/CompanyData.ts models/CompanyListEntry.ts models/CompanyPaged.ts models/CompanyValue.ts +models/ConflictError.ts models/DateValue.ts models/Dropdown.ts models/DropdownValue.ts @@ -59,8 +61,11 @@ models/Location.ts models/LocationValue.ts models/LocationsValue.ts models/Meeting.ts +models/MethodNotAllowedError.ts +models/NotAcceptableError.ts models/NotFoundError.ts models/NotFoundErrors.ts +models/NotImplementedError.ts models/ObjectSerializer.ts models/Opportunity.ts models/OpportunityListEntry.ts @@ -76,11 +81,14 @@ models/PersonsValue.ts models/PhoneCall.ts models/RankedDropdown.ts models/RankedDropdownValue.ts +models/RateLimitError.ts models/SavedView.ts models/SavedViewPaged.ts +models/ServerError.ts models/Tenant.ts models/TextValue.ts models/TextsValue.ts +models/UnprocessableEntityError.ts models/User.ts models/ValidationError.ts models/ValidationErrors.ts diff --git a/src/v2/generated/models/BadRequestError.ts b/src/v2/generated/models/BadRequestError.ts new file mode 100644 index 0000000..cde7313 --- /dev/null +++ b/src/v2/generated/models/BadRequestError.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, 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 ## 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: 2.0.0 + * 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 BadRequestError { + /** + * Error code + */ + 'code': string; + /** + * Error message + */ + 'message': 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": "code", + "baseName": "code", + "type": "string", + "format": "" + }, + { + "name": "message", + "baseName": "message", + "type": "string", + "format": "" + } ]; + + static getAttributeTypeMap() { + return BadRequestError.attributeTypeMap; + } + + public constructor() { + } +} diff --git a/src/v2/generated/models/Company.ts b/src/v2/generated/models/Company.ts index 17be6a2..e3ec270 100644 --- a/src/v2/generated/models/Company.ts +++ b/src/v2/generated/models/Company.ts @@ -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 3e381d0..0a0ebae 100644 --- a/src/v2/generated/models/CompanyData.ts +++ b/src/v2/generated/models/CompanyData.ts @@ -24,7 +24,7 @@ export class CompanyData { /** * The company\'s primary domain */ - 'domain': string; + 'domain': string | null; static readonly discriminator: string | undefined = undefined; diff --git a/src/v2/generated/models/ConflictError.ts b/src/v2/generated/models/ConflictError.ts new file mode 100644 index 0000000..ca73e97 --- /dev/null +++ b/src/v2/generated/models/ConflictError.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, 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 ## 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: 2.0.0 + * 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 ConflictError { + /** + * Error code + */ + 'code': string; + /** + * Error message + */ + 'message': 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": "code", + "baseName": "code", + "type": "string", + "format": "" + }, + { + "name": "message", + "baseName": "message", + "type": "string", + "format": "" + } ]; + + static getAttributeTypeMap() { + return ConflictError.attributeTypeMap; + } + + public constructor() { + } +} diff --git a/src/v2/generated/models/MethodNotAllowedError.ts b/src/v2/generated/models/MethodNotAllowedError.ts new file mode 100644 index 0000000..b67c1ce --- /dev/null +++ b/src/v2/generated/models/MethodNotAllowedError.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, 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 ## 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: 2.0.0 + * 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 MethodNotAllowedError { + /** + * Error code + */ + 'code': string; + /** + * Error message + */ + 'message': 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": "code", + "baseName": "code", + "type": "string", + "format": "" + }, + { + "name": "message", + "baseName": "message", + "type": "string", + "format": "" + } ]; + + static getAttributeTypeMap() { + return MethodNotAllowedError.attributeTypeMap; + } + + public constructor() { + } +} diff --git a/src/v2/generated/models/NotAcceptableError.ts b/src/v2/generated/models/NotAcceptableError.ts new file mode 100644 index 0000000..85392ca --- /dev/null +++ b/src/v2/generated/models/NotAcceptableError.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, 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 ## 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: 2.0.0 + * 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 NotAcceptableError { + /** + * Error code + */ + 'code': string; + /** + * Error message + */ + 'message': 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": "code", + "baseName": "code", + "type": "string", + "format": "" + }, + { + "name": "message", + "baseName": "message", + "type": "string", + "format": "" + } ]; + + static getAttributeTypeMap() { + return NotAcceptableError.attributeTypeMap; + } + + public constructor() { + } +} diff --git a/src/v2/generated/models/NotImplementedError.ts b/src/v2/generated/models/NotImplementedError.ts new file mode 100644 index 0000000..8f8a595 --- /dev/null +++ b/src/v2/generated/models/NotImplementedError.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, 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 ## 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: 2.0.0 + * 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 NotImplementedError { + /** + * Error code + */ + 'code': string; + /** + * Error message + */ + 'message': 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": "code", + "baseName": "code", + "type": "string", + "format": "" + }, + { + "name": "message", + "baseName": "message", + "type": "string", + "format": "" + } ]; + + static getAttributeTypeMap() { + return NotImplementedError.attributeTypeMap; + } + + public constructor() { + } +} diff --git a/src/v2/generated/models/ObjectSerializer.ts b/src/v2/generated/models/ObjectSerializer.ts index 194a6eb..eda4464 100644 --- a/src/v2/generated/models/ObjectSerializer.ts +++ b/src/v2/generated/models/ObjectSerializer.ts @@ -3,6 +3,7 @@ export * from '../models/AuthenticationError.ts'; export * from '../models/AuthenticationErrors.ts'; export * from '../models/AuthorizationError.ts'; export * from '../models/AuthorizationErrors.ts'; +export * from '../models/BadRequestError.ts'; export * from '../models/ChatMessage.ts'; export * from '../models/CompaniesValue.ts'; export * from '../models/Company.ts'; @@ -10,6 +11,7 @@ export * from '../models/CompanyData.ts'; export * from '../models/CompanyListEntry.ts'; export * from '../models/CompanyPaged.ts'; export * from '../models/CompanyValue.ts'; +export * from '../models/ConflictError.ts'; export * from '../models/DateValue.ts'; export * from '../models/Dropdown.ts'; export * from '../models/DropdownValue.ts'; @@ -38,8 +40,11 @@ export * from '../models/Location.ts'; export * from '../models/LocationValue.ts'; export * from '../models/LocationsValue.ts'; export * from '../models/Meeting.ts'; +export * from '../models/MethodNotAllowedError.ts'; +export * from '../models/NotAcceptableError.ts'; export * from '../models/NotFoundError.ts'; export * from '../models/NotFoundErrors.ts'; +export * from '../models/NotImplementedError.ts'; export * from '../models/Opportunity.ts'; export * from '../models/OpportunityListEntry.ts'; export * from '../models/OpportunityPaged.ts'; @@ -54,11 +59,14 @@ export * from '../models/PersonsValue.ts'; export * from '../models/PhoneCall.ts'; export * from '../models/RankedDropdown.ts'; export * from '../models/RankedDropdownValue.ts'; +export * from '../models/RateLimitError.ts'; export * from '../models/SavedView.ts'; export * from '../models/SavedViewPaged.ts'; +export * from '../models/ServerError.ts'; export * from '../models/Tenant.ts'; export * from '../models/TextValue.ts'; export * from '../models/TextsValue.ts'; +export * from '../models/UnprocessableEntityError.ts'; export * from '../models/User.ts'; export * from '../models/ValidationError.ts'; export * from '../models/ValidationErrors.ts'; @@ -69,6 +77,7 @@ import { AuthenticationError } from '../models/AuthenticationError.ts'; import { AuthenticationErrors } from '../models/AuthenticationErrors.ts'; import { AuthorizationError } from '../models/AuthorizationError.ts'; import { AuthorizationErrors } from '../models/AuthorizationErrors.ts'; +import { BadRequestError } from '../models/BadRequestError.ts'; import { ChatMessage , ChatMessageDirectionEnum } from '../models/ChatMessage.ts'; import { CompaniesValue } from '../models/CompaniesValue.ts'; import { Company } from '../models/Company.ts'; @@ -76,6 +85,7 @@ import { CompanyData } from '../models/CompanyData.ts'; import { CompanyListEntry } from '../models/CompanyListEntry.ts'; import { CompanyPaged } from '../models/CompanyPaged.ts'; import { CompanyValue } from '../models/CompanyValue.ts'; +import { ConflictError } from '../models/ConflictError.ts'; import { DateValue } from '../models/DateValue.ts'; import { Dropdown } from '../models/Dropdown.ts'; import { DropdownValue } from '../models/DropdownValue.ts'; @@ -104,8 +114,11 @@ import { Location } from '../models/Location.ts'; import { LocationValue } from '../models/LocationValue.ts'; import { LocationsValue } from '../models/LocationsValue.ts'; import { Meeting } from '../models/Meeting.ts'; +import { MethodNotAllowedError } from '../models/MethodNotAllowedError.ts'; +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 { Opportunity } from '../models/Opportunity.ts'; import { OpportunityListEntry } from '../models/OpportunityListEntry.ts'; import { OpportunityPaged } from '../models/OpportunityPaged.ts'; @@ -120,11 +133,14 @@ import { PersonsValue } from '../models/PersonsValue.ts'; import { PhoneCall } from '../models/PhoneCall.ts'; import { RankedDropdown } from '../models/RankedDropdown.ts'; import { RankedDropdownValue } from '../models/RankedDropdownValue.ts'; +import { RateLimitError } from '../models/RateLimitError.ts'; import { SavedView , SavedViewTypeEnum } from '../models/SavedView.ts'; import { SavedViewPaged } from '../models/SavedViewPaged.ts'; +import { ServerError } from '../models/ServerError.ts'; import { Tenant } from '../models/Tenant.ts'; import { TextValue, TextValueTypeEnum } from '../models/TextValue.ts'; import { TextsValue } from '../models/TextsValue.ts'; +import { UnprocessableEntityError } from '../models/UnprocessableEntityError.ts'; import { User } from '../models/User.ts'; import { ValidationError } from '../models/ValidationError.ts'; import { ValidationErrors } from '../models/ValidationErrors.ts'; @@ -166,6 +182,7 @@ let typeMap: {[index: string]: any} = { "AuthenticationErrors": AuthenticationErrors, "AuthorizationError": AuthorizationError, "AuthorizationErrors": AuthorizationErrors, + "BadRequestError": BadRequestError, "ChatMessage": ChatMessage, "CompaniesValue": CompaniesValue, "Company": Company, @@ -173,6 +190,7 @@ let typeMap: {[index: string]: any} = { "CompanyListEntry": CompanyListEntry, "CompanyPaged": CompanyPaged, "CompanyValue": CompanyValue, + "ConflictError": ConflictError, "DateValue": DateValue, "Dropdown": Dropdown, "DropdownValue": DropdownValue, @@ -201,8 +219,11 @@ let typeMap: {[index: string]: any} = { "LocationValue": LocationValue, "LocationsValue": LocationsValue, "Meeting": Meeting, + "MethodNotAllowedError": MethodNotAllowedError, + "NotAcceptableError": NotAcceptableError, "NotFoundError": NotFoundError, "NotFoundErrors": NotFoundErrors, + "NotImplementedError": NotImplementedError, "Opportunity": Opportunity, "OpportunityListEntry": OpportunityListEntry, "OpportunityPaged": OpportunityPaged, @@ -217,11 +238,14 @@ let typeMap: {[index: string]: any} = { "PhoneCall": PhoneCall, "RankedDropdown": RankedDropdown, "RankedDropdownValue": RankedDropdownValue, + "RateLimitError": RateLimitError, "SavedView": SavedView, "SavedViewPaged": SavedViewPaged, + "ServerError": ServerError, "Tenant": Tenant, "TextValue": TextValue, "TextsValue": TextsValue, + "UnprocessableEntityError": UnprocessableEntityError, "User": User, "ValidationError": ValidationError, "ValidationErrors": ValidationErrors, diff --git a/src/v2/generated/models/RateLimitError.ts b/src/v2/generated/models/RateLimitError.ts new file mode 100644 index 0000000..7c90d55 --- /dev/null +++ b/src/v2/generated/models/RateLimitError.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, 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 ## 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: 2.0.0 + * 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 RateLimitError { + /** + * Error code + */ + 'code': string; + /** + * Error message + */ + 'message': 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": "code", + "baseName": "code", + "type": "string", + "format": "" + }, + { + "name": "message", + "baseName": "message", + "type": "string", + "format": "" + } ]; + + static getAttributeTypeMap() { + return RateLimitError.attributeTypeMap; + } + + public constructor() { + } +} diff --git a/src/v2/generated/models/ServerError.ts b/src/v2/generated/models/ServerError.ts new file mode 100644 index 0000000..6e7a54e --- /dev/null +++ b/src/v2/generated/models/ServerError.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, 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 ## 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: 2.0.0 + * 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 ServerError { + /** + * Error code + */ + 'code': string; + /** + * Error message + */ + 'message': 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": "code", + "baseName": "code", + "type": "string", + "format": "" + }, + { + "name": "message", + "baseName": "message", + "type": "string", + "format": "" + } ]; + + static getAttributeTypeMap() { + return ServerError.attributeTypeMap; + } + + public constructor() { + } +} diff --git a/src/v2/generated/models/UnprocessableEntityError.ts b/src/v2/generated/models/UnprocessableEntityError.ts new file mode 100644 index 0000000..836eb16 --- /dev/null +++ b/src/v2/generated/models/UnprocessableEntityError.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, 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 ## 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: 2.0.0 + * 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 UnprocessableEntityError { + /** + * Error code + */ + 'code': string; + /** + * Error message + */ + 'message': 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": "code", + "baseName": "code", + "type": "string", + "format": "" + }, + { + "name": "message", + "baseName": "message", + "type": "string", + "format": "" + } ]; + + static getAttributeTypeMap() { + return UnprocessableEntityError.attributeTypeMap; + } + + public constructor() { + } +} diff --git a/src/v2/generated/models/all.ts b/src/v2/generated/models/all.ts index b01e638..33be023 100644 --- a/src/v2/generated/models/all.ts +++ b/src/v2/generated/models/all.ts @@ -3,6 +3,7 @@ export * from '../models/AuthenticationError.ts' export * from '../models/AuthenticationErrors.ts' export * from '../models/AuthorizationError.ts' export * from '../models/AuthorizationErrors.ts' +export * from '../models/BadRequestError.ts' export * from '../models/ChatMessage.ts' export * from '../models/CompaniesValue.ts' export * from '../models/Company.ts' @@ -10,6 +11,7 @@ export * from '../models/CompanyData.ts' export * from '../models/CompanyListEntry.ts' export * from '../models/CompanyPaged.ts' export * from '../models/CompanyValue.ts' +export * from '../models/ConflictError.ts' export * from '../models/DateValue.ts' export * from '../models/Dropdown.ts' export * from '../models/DropdownValue.ts' @@ -38,8 +40,11 @@ export * from '../models/Location.ts' export * from '../models/LocationValue.ts' export * from '../models/LocationsValue.ts' export * from '../models/Meeting.ts' +export * from '../models/MethodNotAllowedError.ts' +export * from '../models/NotAcceptableError.ts' export * from '../models/NotFoundError.ts' export * from '../models/NotFoundErrors.ts' +export * from '../models/NotImplementedError.ts' export * from '../models/Opportunity.ts' export * from '../models/OpportunityListEntry.ts' export * from '../models/OpportunityPaged.ts' @@ -54,11 +59,14 @@ export * from '../models/PersonsValue.ts' export * from '../models/PhoneCall.ts' export * from '../models/RankedDropdown.ts' export * from '../models/RankedDropdownValue.ts' +export * from '../models/RateLimitError.ts' export * from '../models/SavedView.ts' export * from '../models/SavedViewPaged.ts' +export * from '../models/ServerError.ts' export * from '../models/Tenant.ts' export * from '../models/TextValue.ts' export * from '../models/TextsValue.ts' +export * from '../models/UnprocessableEntityError.ts' export * from '../models/User.ts' export * from '../models/ValidationError.ts' export * from '../models/ValidationErrors.ts' diff --git a/src/v2/generated/types/ObjectParamAPI.ts b/src/v2/generated/types/ObjectParamAPI.ts index 49d5099..69cc86a 100644 --- a/src/v2/generated/types/ObjectParamAPI.ts +++ b/src/v2/generated/types/ObjectParamAPI.ts @@ -6,6 +6,7 @@ import { AuthenticationError } from '../models/AuthenticationError.ts'; import { AuthenticationErrors } from '../models/AuthenticationErrors.ts'; import { AuthorizationError } from '../models/AuthorizationError.ts'; import { AuthorizationErrors } from '../models/AuthorizationErrors.ts'; +import { BadRequestError } from '../models/BadRequestError.ts'; import { ChatMessage } from '../models/ChatMessage.ts'; import { CompaniesValue } from '../models/CompaniesValue.ts'; import { Company } from '../models/Company.ts'; @@ -13,6 +14,7 @@ import { CompanyData } from '../models/CompanyData.ts'; import { CompanyListEntry } from '../models/CompanyListEntry.ts'; import { CompanyPaged } from '../models/CompanyPaged.ts'; import { CompanyValue } from '../models/CompanyValue.ts'; +import { ConflictError } from '../models/ConflictError.ts'; import { DateValue } from '../models/DateValue.ts'; import { Dropdown } from '../models/Dropdown.ts'; import { DropdownValue } from '../models/DropdownValue.ts'; @@ -41,8 +43,11 @@ import { Location } from '../models/Location.ts'; import { LocationValue } from '../models/LocationValue.ts'; import { LocationsValue } from '../models/LocationsValue.ts'; import { Meeting } from '../models/Meeting.ts'; +import { MethodNotAllowedError } from '../models/MethodNotAllowedError.ts'; +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 { Opportunity } from '../models/Opportunity.ts'; import { OpportunityListEntry } from '../models/OpportunityListEntry.ts'; import { OpportunityPaged } from '../models/OpportunityPaged.ts'; @@ -57,11 +62,14 @@ import { PersonsValue } from '../models/PersonsValue.ts'; import { PhoneCall } from '../models/PhoneCall.ts'; import { RankedDropdown } from '../models/RankedDropdown.ts'; import { RankedDropdownValue } from '../models/RankedDropdownValue.ts'; +import { RateLimitError } from '../models/RateLimitError.ts'; import { SavedView } from '../models/SavedView.ts'; import { SavedViewPaged } from '../models/SavedViewPaged.ts'; +import { ServerError } from '../models/ServerError.ts'; import { Tenant } from '../models/Tenant.ts'; import { TextValue } from '../models/TextValue.ts'; import { TextsValue } from '../models/TextsValue.ts'; +import { UnprocessableEntityError } from '../models/UnprocessableEntityError.ts'; import { User } from '../models/User.ts'; import { ValidationError } from '../models/ValidationError.ts'; import { ValidationErrors } from '../models/ValidationErrors.ts'; diff --git a/src/v2/generated/types/ObservableAPI.ts b/src/v2/generated/types/ObservableAPI.ts index 3bb42f6..0d300f1 100644 --- a/src/v2/generated/types/ObservableAPI.ts +++ b/src/v2/generated/types/ObservableAPI.ts @@ -7,6 +7,7 @@ import { AuthenticationError } from '../models/AuthenticationError.ts'; import { AuthenticationErrors } from '../models/AuthenticationErrors.ts'; import { AuthorizationError } from '../models/AuthorizationError.ts'; import { AuthorizationErrors } from '../models/AuthorizationErrors.ts'; +import { BadRequestError } from '../models/BadRequestError.ts'; import { ChatMessage } from '../models/ChatMessage.ts'; import { CompaniesValue } from '../models/CompaniesValue.ts'; import { Company } from '../models/Company.ts'; @@ -14,6 +15,7 @@ import { CompanyData } from '../models/CompanyData.ts'; import { CompanyListEntry } from '../models/CompanyListEntry.ts'; import { CompanyPaged } from '../models/CompanyPaged.ts'; import { CompanyValue } from '../models/CompanyValue.ts'; +import { ConflictError } from '../models/ConflictError.ts'; import { DateValue } from '../models/DateValue.ts'; import { Dropdown } from '../models/Dropdown.ts'; import { DropdownValue } from '../models/DropdownValue.ts'; @@ -42,8 +44,11 @@ import { Location } from '../models/Location.ts'; import { LocationValue } from '../models/LocationValue.ts'; import { LocationsValue } from '../models/LocationsValue.ts'; import { Meeting } from '../models/Meeting.ts'; +import { MethodNotAllowedError } from '../models/MethodNotAllowedError.ts'; +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 { Opportunity } from '../models/Opportunity.ts'; import { OpportunityListEntry } from '../models/OpportunityListEntry.ts'; import { OpportunityPaged } from '../models/OpportunityPaged.ts'; @@ -58,11 +63,14 @@ import { PersonsValue } from '../models/PersonsValue.ts'; import { PhoneCall } from '../models/PhoneCall.ts'; import { RankedDropdown } from '../models/RankedDropdown.ts'; import { RankedDropdownValue } from '../models/RankedDropdownValue.ts'; +import { RateLimitError } from '../models/RateLimitError.ts'; import { SavedView } from '../models/SavedView.ts'; import { SavedViewPaged } from '../models/SavedViewPaged.ts'; +import { ServerError } from '../models/ServerError.ts'; import { Tenant } from '../models/Tenant.ts'; import { TextValue } from '../models/TextValue.ts'; import { TextsValue } from '../models/TextsValue.ts'; +import { UnprocessableEntityError } from '../models/UnprocessableEntityError.ts'; import { User } from '../models/User.ts'; import { ValidationError } from '../models/ValidationError.ts'; import { ValidationErrors } from '../models/ValidationErrors.ts'; diff --git a/src/v2/generated/types/PromiseAPI.ts b/src/v2/generated/types/PromiseAPI.ts index 712b0a0..9e26091 100644 --- a/src/v2/generated/types/PromiseAPI.ts +++ b/src/v2/generated/types/PromiseAPI.ts @@ -6,6 +6,7 @@ import { AuthenticationError } from '../models/AuthenticationError.ts'; import { AuthenticationErrors } from '../models/AuthenticationErrors.ts'; import { AuthorizationError } from '../models/AuthorizationError.ts'; import { AuthorizationErrors } from '../models/AuthorizationErrors.ts'; +import { BadRequestError } from '../models/BadRequestError.ts'; import { ChatMessage } from '../models/ChatMessage.ts'; import { CompaniesValue } from '../models/CompaniesValue.ts'; import { Company } from '../models/Company.ts'; @@ -13,6 +14,7 @@ import { CompanyData } from '../models/CompanyData.ts'; import { CompanyListEntry } from '../models/CompanyListEntry.ts'; import { CompanyPaged } from '../models/CompanyPaged.ts'; import { CompanyValue } from '../models/CompanyValue.ts'; +import { ConflictError } from '../models/ConflictError.ts'; import { DateValue } from '../models/DateValue.ts'; import { Dropdown } from '../models/Dropdown.ts'; import { DropdownValue } from '../models/DropdownValue.ts'; @@ -41,8 +43,11 @@ import { Location } from '../models/Location.ts'; import { LocationValue } from '../models/LocationValue.ts'; import { LocationsValue } from '../models/LocationsValue.ts'; import { Meeting } from '../models/Meeting.ts'; +import { MethodNotAllowedError } from '../models/MethodNotAllowedError.ts'; +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 { Opportunity } from '../models/Opportunity.ts'; import { OpportunityListEntry } from '../models/OpportunityListEntry.ts'; import { OpportunityPaged } from '../models/OpportunityPaged.ts'; @@ -57,11 +62,14 @@ import { PersonsValue } from '../models/PersonsValue.ts'; import { PhoneCall } from '../models/PhoneCall.ts'; import { RankedDropdown } from '../models/RankedDropdown.ts'; import { RankedDropdownValue } from '../models/RankedDropdownValue.ts'; +import { RateLimitError } from '../models/RateLimitError.ts'; import { SavedView } from '../models/SavedView.ts'; import { SavedViewPaged } from '../models/SavedViewPaged.ts'; +import { ServerError } from '../models/ServerError.ts'; import { Tenant } from '../models/Tenant.ts'; import { TextValue } from '../models/TextValue.ts'; import { TextsValue } from '../models/TextsValue.ts'; +import { UnprocessableEntityError } from '../models/UnprocessableEntityError.ts'; import { User } from '../models/User.ts'; import { ValidationError } from '../models/ValidationError.ts'; import { ValidationErrors } from '../models/ValidationErrors.ts'; From dddd94595a36e59461ec4e2c52bcf537466f8780 Mon Sep 17 00:00:00 2001 From: Joscha Feth Date: Tue, 8 Oct 2024 10:38:58 +0100 Subject: [PATCH 4/9] chore: update spec --- openapi/2024-09-28.json | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/openapi/2024-09-28.json b/openapi/2024-09-28.json index 10a18ce..b6aeb5f 100644 --- a/openapi/2024-09-28.json +++ b/openapi/2024-09-28.json @@ -1841,6 +1841,30 @@ ], "type": "object" }, + "UnsupportedMediaTypeError": { + "examples": [ + { + "code": "unsupported-media-type", + "message": "🚨 Error! Sound the alarm! 🚨" + } + ], + "properties": { + "code": { + "description": "Error code", + "const": "unsupported-media-type", + "type": "string" + }, + "message": { + "description": "Error message", + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "type": "object" + }, "Tenant": { "examples": [ { From ed52c780cc750dfc4fc3603f1b8366dfe30c1dc9 Mon Sep 17 00:00:00 2001 From: Joscha Feth Date: Tue, 8 Oct 2024 10:39:27 +0100 Subject: [PATCH 5/9] refactor: move spec --- openapi/{2024-09-28.json => 2024-10-08.json} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename openapi/{2024-09-28.json => 2024-10-08.json} (100%) diff --git a/openapi/2024-09-28.json b/openapi/2024-10-08.json similarity index 100% rename from openapi/2024-09-28.json rename to openapi/2024-10-08.json From 25de5e28d21afefa1d3356a6a57c481ea053e255 Mon Sep 17 00:00:00 2001 From: Joscha Feth Date: Tue, 8 Oct 2024 10:44:35 +0100 Subject: [PATCH 6/9] chore: regenerate spec --- deno.jsonc | 2 +- deno.lock | 113 ++++++++++++ openapitools.json | 2 +- src/.gitattributes | 1 - src/v2/generated/.gitattributes | 8 + src/v2/generated/.openapi-generator/FILES | 2 + src/v2/generated/AuthApi.md | 14 +- src/v2/generated/CompaniesApi.md | 107 ++++++------ src/v2/generated/ListsApi.md | 145 ++++++++------- src/v2/generated/OpportunitiesApi.md | 38 ++-- src/v2/generated/PersonsApi.md | 107 ++++++------ src/v2/generated/http/http.ts | 14 +- .../generated/models/AuthenticationError.ts | 9 +- src/v2/generated/models/AuthorizationError.ts | 9 +- src/v2/generated/models/BadRequestError.ts | 9 +- src/v2/generated/models/ChatMessage.ts | 7 +- src/v2/generated/models/CompaniesValue.ts | 11 +- src/v2/generated/models/CompanyListEntry.ts | 9 +- src/v2/generated/models/CompanyValue.ts | 9 +- src/v2/generated/models/ConflictError.ts | 9 +- src/v2/generated/models/DateValue.ts | 9 +- src/v2/generated/models/DropdownValue.ts | 9 +- src/v2/generated/models/DropdownsValue.ts | 11 +- src/v2/generated/models/Email.ts | 9 +- src/v2/generated/models/Field.ts | 3 +- src/v2/generated/models/FieldMetadata.ts | 3 +- src/v2/generated/models/FloatValue.ts | 9 +- src/v2/generated/models/FloatsValue.ts | 11 +- src/v2/generated/models/FormulaValue.ts | 9 +- src/v2/generated/models/Grant.ts | 9 +- src/v2/generated/models/InteractionValue.ts | 9 +- .../models/ListEntryWithEntityPaged.ts | 2 +- src/v2/generated/models/LocationValue.ts | 9 +- src/v2/generated/models/LocationsValue.ts | 11 +- src/v2/generated/models/Meeting.ts | 9 +- .../generated/models/MethodNotAllowedError.ts | 9 +- src/v2/generated/models/NotAcceptableError.ts | 9 +- src/v2/generated/models/NotFoundError.ts | 9 +- .../generated/models/NotImplementedError.ts | 9 +- src/v2/generated/models/ObjectSerializer.ts | 164 ++++++++++++----- .../generated/models/OpportunityListEntry.ts | 9 +- src/v2/generated/models/PersonListEntry.ts | 9 +- src/v2/generated/models/PersonValue.ts | 9 +- src/v2/generated/models/PersonsValue.ts | 11 +- src/v2/generated/models/PhoneCall.ts | 9 +- .../generated/models/RankedDropdownValue.ts | 9 +- src/v2/generated/models/RateLimitError.ts | 9 +- src/v2/generated/models/ServerError.ts | 9 +- src/v2/generated/models/TextsValue.ts | 11 +- .../models/UnprocessableEntityError.ts | 9 +- .../models/UnsupportedMediaTypeError.ts | 54 ++++++ src/v2/generated/models/ValidationError.ts | 9 +- src/v2/generated/models/all.ts | 1 + src/v2/generated/types/ObjectParamAPI.ts | 115 ++++++++++++ src/v2/generated/types/ObservableAPI.ts | 165 +++++++++--------- src/v2/generated/types/PromiseAPI.ts | 165 +++++++++--------- 56 files changed, 1037 insertions(+), 513 deletions(-) delete mode 100644 src/.gitattributes create mode 100644 src/v2/generated/.gitattributes create mode 100644 src/v2/generated/models/UnsupportedMediaTypeError.ts diff --git a/deno.jsonc b/deno.jsonc index 547b11a..bfaf25a 100644 --- a/deno.jsonc +++ b/deno.jsonc @@ -25,7 +25,7 @@ "format": "deno fmt && nixpkgs-fmt *.nix && yamllint . && yamlfmt .", "lint": "deno lint", "docs": "deno run --allow-read --allow-env --allow-run --allow-write=./docs/ npm:typedoc@0.26.6", - "generate-v2-client": "rm -rf src/v2/generated && deno run --allow-read --allow-run --allow-env --allow-write=openapitools.json,node_modules,/tmp,/var --allow-net='search.maven.org,repo1.maven.org,oss.sonatype.org:443' npm:@openapitools/openapi-generator-cli@2.13.5 generate", + "generate-v2-client": "rm -rf src/v2/generated && deno run --allow-read --allow-run --allow-env --allow-write=openapitools.json,node_modules,/tmp,/var --allow-net='search.maven.org,repo1.maven.org,oss.sonatype.org:443' npm:@openapitools/openapi-generator-cli@2.14.0 generate", "update-deno-lock": "deno cache --lock-write src/index.ts", "update-flake-lock": "nix --option commit-lockfile-summary 'chore: update flake.lock' flake update --commit-lock-file", "update": "deno run --allow-env --allow-read --allow-write='~/.local,.' --allow-run=git,deno --allow-net=jsr.io jsr:@molt/cli", diff --git a/deno.lock b/deno.lock index dec0f0e..f0a0044 100644 --- a/deno.lock +++ b/deno.lock @@ -41,6 +41,7 @@ "jsr:@ts-morph/common@^0.24.0": "jsr:@ts-morph/common@0.24.0", "npm:@openapitools/openapi-generator-cli@2.13.4": "npm:@openapitools/openapi-generator-cli@2.13.4_@nestjs+common@10.3.0__reflect-metadata@0.1.13__rxjs@7.8.1_axios@1.6.8_rxjs@7.8.1_reflect-metadata@0.1.13", "npm:@openapitools/openapi-generator-cli@2.13.5": "npm:@openapitools/openapi-generator-cli@2.13.5_@nestjs+common@10.3.0__reflect-metadata@0.1.13__rxjs@7.8.1_axios@1.7.4_rxjs@7.8.1_reflect-metadata@0.1.13", + "npm:@openapitools/openapi-generator-cli@2.14.0": "npm:@openapitools/openapi-generator-cli@2.14.0_@nestjs+common@10.4.3__reflect-metadata@0.1.13__rxjs@7.8.1_axios@1.7.7_rxjs@7.8.1_reflect-metadata@0.1.13", "npm:@types/node": "npm:@types/node@18.16.19", "npm:axios-mock-adapter@^2.0.0": "npm:axios-mock-adapter@2.0.0_axios@1.7.4", "npm:axios@^1.7.3": "npm:axios@1.7.4", @@ -238,6 +239,14 @@ "rxjs": "rxjs@7.8.1" } }, + "@nestjs/axios@3.0.3_@nestjs+common@10.4.3__reflect-metadata@0.1.13__rxjs@7.8.1_axios@1.7.7_rxjs@7.8.1_reflect-metadata@0.1.13": { + "integrity": "sha512-h6TCn3yJwD6OKqqqfmtRS5Zo4E46Ip2n+gK1sqwzNBC+qxQ9xpCu+ODVRFur6V3alHSCSBxb3nNtt73VEdluyA==", + "dependencies": { + "@nestjs/common": "@nestjs/common@10.4.3_reflect-metadata@0.1.13_rxjs@7.8.1", + "axios": "axios@1.7.7", + "rxjs": "rxjs@7.8.1" + } + }, "@nestjs/common@10.3.0_reflect-metadata@0.1.13_rxjs@7.8.1": { "integrity": "sha512-DGv34UHsZBxCM3H5QGE2XE/+oLJzz5+714JQjBhjD9VccFlQs3LRxo/epso4l7nJIiNlZkPyIUC8WzfU/5RTsQ==", "dependencies": { @@ -248,6 +257,16 @@ "uid": "uid@2.0.2" } }, + "@nestjs/common@10.4.3_reflect-metadata@0.1.13_rxjs@7.8.1": { + "integrity": "sha512-4hbLd3XIJubHSylYd/1WSi4VQvG68KM/ECYpMDqA3k3J1/T17SAg40sDoq3ZoO5OZgU0xuNyjuISdOTjs11qVg==", + "dependencies": { + "iterare": "iterare@1.2.1", + "reflect-metadata": "reflect-metadata@0.1.13", + "rxjs": "rxjs@7.8.1", + "tslib": "tslib@2.7.0", + "uid": "uid@2.0.2" + } + }, "@nestjs/core@10.3.0_@nestjs+common@10.3.0__reflect-metadata@0.1.13__rxjs@7.8.1_reflect-metadata@0.1.13_rxjs@7.8.1": { "integrity": "sha512-N06P5ncknW/Pm8bj964WvLIZn2gNhHliCBoAO1LeBvNImYkecqKcrmLbY49Fa1rmMfEM3MuBHeDys3edeuYAOA==", "dependencies": { @@ -262,6 +281,20 @@ "uid": "uid@2.0.2" } }, + "@nestjs/core@10.4.3_@nestjs+common@10.4.3__reflect-metadata@0.1.13__rxjs@7.8.1_reflect-metadata@0.1.13_rxjs@7.8.1": { + "integrity": "sha512-6OQz+5C8mT8yRtfvE5pPCq+p6w5jDot+oQku1KzQ24ABn+lay1KGuJwcKZhdVNuselx+8xhdMxknZTA8wrGLIg==", + "dependencies": { + "@nestjs/common": "@nestjs/common@10.4.3_reflect-metadata@0.1.13_rxjs@7.8.1", + "@nuxtjs/opencollective": "@nuxtjs/opencollective@0.3.2", + "fast-safe-stringify": "fast-safe-stringify@2.1.1", + "iterare": "iterare@1.2.1", + "path-to-regexp": "path-to-regexp@3.3.0", + "reflect-metadata": "reflect-metadata@0.1.13", + "rxjs": "rxjs@7.8.1", + "tslib": "tslib@2.7.0", + "uid": "uid@2.0.2" + } + }, "@nuxtjs/opencollective@0.3.2": { "integrity": "sha512-um0xL3fO7Mf4fDxcqx9KryrB7zgRM5JSlvGN5AGkP6JLM5XEKyjeAiPbNxdXVXQ16isuAhYpvP88NgL2BGd6aA==", "dependencies": { @@ -316,6 +349,29 @@ "tslib": "tslib@2.6.2" } }, + "@openapitools/openapi-generator-cli@2.14.0_@nestjs+common@10.4.3__reflect-metadata@0.1.13__rxjs@7.8.1_axios@1.7.7_rxjs@7.8.1_reflect-metadata@0.1.13": { + "integrity": "sha512-k+ioQLtXLXgNbhQbp1UOxtaUnnYTWwAPev88hP5qauFA+eq4NyeQGNojknFssXg2x0VT0TUGmU3PZ2DiQ70IVg==", + "dependencies": { + "@nestjs/axios": "@nestjs/axios@3.0.3_@nestjs+common@10.4.3__reflect-metadata@0.1.13__rxjs@7.8.1_axios@1.7.7_rxjs@7.8.1_reflect-metadata@0.1.13", + "@nestjs/common": "@nestjs/common@10.4.3_reflect-metadata@0.1.13_rxjs@7.8.1", + "@nestjs/core": "@nestjs/core@10.4.3_@nestjs+common@10.4.3__reflect-metadata@0.1.13__rxjs@7.8.1_reflect-metadata@0.1.13_rxjs@7.8.1", + "@nuxtjs/opencollective": "@nuxtjs/opencollective@0.3.2", + "axios": "axios@1.7.7", + "chalk": "chalk@4.1.2", + "commander": "commander@8.3.0", + "compare-versions": "compare-versions@4.1.4", + "concurrently": "concurrently@6.5.1", + "console.table": "console.table@0.10.0", + "fs-extra": "fs-extra@10.1.0", + "glob": "glob@9.3.5", + "https-proxy-agent": "https-proxy-agent@7.0.5", + "inquirer": "inquirer@8.2.6", + "lodash": "lodash@4.17.21", + "reflect-metadata": "reflect-metadata@0.1.13", + "rxjs": "rxjs@7.8.1", + "tslib": "tslib@2.7.0" + } + }, "@shikijs/core@1.16.1": { "integrity": "sha512-aI0hBtw+a6KsJp2jcD4YuQqKpeCbURMZbhHVozDknJpm+KJqeMRkEnfBC8BaKE/5XC+uofPgCLsa/TkTk0Ba0w==", "dependencies": { @@ -403,6 +459,14 @@ "proxy-from-env": "proxy-from-env@1.1.0" } }, + "axios@1.7.7": { + "integrity": "sha512-S4kL7XrjgBmvdGut0sN3yJxqYzrDOnivkBiN0OFs6hLiUam3UPvswUo0kqGyhqUZGEOytHyumEdXsAkgCOUf3Q==", + "dependencies": { + "follow-redirects": "follow-redirects@1.15.6", + "form-data": "form-data@4.0.0", + "proxy-from-env": "proxy-from-env@1.1.0" + } + }, "balanced-match@1.0.2": { "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==", "dependencies": {} @@ -656,6 +720,15 @@ "path-is-absolute": "path-is-absolute@1.0.1" } }, + "glob@9.3.5": { + "integrity": "sha512-e1LleDykUz2Iu+MTYdkSsuWX8lvAjAcs0Xef0lNIu0S2wOAzuTxCJtcd9S3cijlwYF18EsU3rzb8jPVobxDh9Q==", + "dependencies": { + "fs.realpath": "fs.realpath@1.0.0", + "minimatch": "minimatch@8.0.4", + "minipass": "minipass@4.2.8", + "path-scurry": "path-scurry@1.11.1" + } + }, "graceful-fs@4.2.11": { "integrity": "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==", "dependencies": {} @@ -671,6 +744,13 @@ "debug": "debug@4.3.5" } }, + "https-proxy-agent@7.0.5": { + "integrity": "sha512-1e4Wqeblerz+tMKPIq2EMGiiWW1dIjZOksyHWSUm1rmuvw/how9hBHZ38lAGj5ID4Ik6EdkOw7NmWPy6LAwalw==", + "dependencies": { + "agent-base": "agent-base@7.1.1", + "debug": "debug@4.3.5" + } + }, "iconv-lite@0.4.24": { "integrity": "sha512-v3MXnZAcvnywkTUEZomIActle7RXXeedOR31wwl7VlyoXO4Qi9arvSenNQWne1TcRwhCL1HwLI21bEqdpj8/rA==", "dependencies": { @@ -764,6 +844,10 @@ "is-unicode-supported": "is-unicode-supported@0.1.0" } }, + "lru-cache@10.4.3": { + "integrity": "sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ==", + "dependencies": {} + }, "lunr@2.3.9": { "integrity": "sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==", "dependencies": {} @@ -807,12 +891,26 @@ "brace-expansion": "brace-expansion@1.1.11" } }, + "minimatch@8.0.4": { + "integrity": "sha512-W0Wvr9HyFXZRGIDgCicunpQ299OKXs9RgZfaukz4qAW/pJhcpUfupc9c+OObPOFueNy8VSrZgEmDtk6Kh4WzDA==", + "dependencies": { + "brace-expansion": "brace-expansion@2.0.1" + } + }, "minimatch@9.0.5": { "integrity": "sha512-G6T0ZX48xgozx7587koeX9Ys2NYy6Gmv//P89sEte9V9whIapMNF4idKxnW2QtCcLiTWlb/wfCabAtAFWhhBow==", "dependencies": { "brace-expansion": "brace-expansion@2.0.1" } }, + "minipass@4.2.8": { + "integrity": "sha512-fNzuVyifolSLFL4NzpF+wEF4qrgqaaKX0haXPQEdQ7NKAN+WecoKMHV09YcuL/DHxrUsYQOK3MiuDf7Ip2OXfQ==", + "dependencies": {} + }, + "minipass@7.1.2": { + "integrity": "sha512-qOOzS1cBTWYF4BH8fVePDBOO9iptMnGUEZwNc/cMWnTV2nVLZ7VoNWEPHkYczZA0pdoA7dl6e7FL659nX9S2aw==", + "dependencies": {} + }, "ms@2.1.2": { "integrity": "sha512-sGkPx+VjMtmA6MX27oA4FBFELFCZZ4S4XqeGOXCv68tT+jb3vk/RyaKWP0PTKyWtmLSM0b+adUTEvbs1PEaH2w==", "dependencies": {} @@ -865,10 +963,21 @@ "integrity": "sha512-AVbw3UJ2e9bq64vSaS9Am0fje1Pa8pbGqTTsmXfaIiMpnr5DlDhfJOuLj9Sf95ZPVDAUerDfEk88MPmPe7UCQg==", "dependencies": {} }, + "path-scurry@1.11.1": { + "integrity": "sha512-Xa4Nw17FS9ApQFJ9umLiJS4orGjm7ZzwUrwamcGQuHSzDyth9boKDaycYdDcZDuqYATXw4HFXgaqWTctW/v1HA==", + "dependencies": { + "lru-cache": "lru-cache@10.4.3", + "minipass": "minipass@7.1.2" + } + }, "path-to-regexp@3.2.0": { "integrity": "sha512-jczvQbCUS7XmS7o+y1aEO9OBVFeZBQ1MDSEqmO7xSoPgOPoowY/SxLpZ6Vh97/8qHZOteiCKb7gkG9gA2ZUxJA==", "dependencies": {} }, + "path-to-regexp@3.3.0": { + "integrity": "sha512-qyCH421YQPS2WFDxDjftfc1ZR5WKQzVzqsp4n9M2kQhVOo/ByahFoUNJfl58kOcEGfQ//7weFTDhm+ss8Ecxgw==", + "dependencies": {} + }, "proxy-from-env@1.1.0": { "integrity": "sha512-D+zkORCbA9f1tdWRK0RaCR3GPv50cMxcrz4X8k5LTSUD1Dkw47mKJEZQNunItRTkWwgtaUSo1RVFRIG9ZXiFYg==", "dependencies": {} @@ -1015,6 +1124,10 @@ "integrity": "sha512-AEYxH93jGFPn/a2iVAwW87VuUIkR1FVUKB77NwMF7nBTDkDrrT/Hpt/IrCJ0QXhW27jTBDcf5ZY7w6RiqTMw2Q==", "dependencies": {} }, + "tslib@2.7.0": { + "integrity": "sha512-gLXCKdN1/j47AiHiOkJN69hJmcbGTHI0ImLmbYLHykhgeN0jVGola9yVjFgzCUklsZQMW55o+dW7IXv3RCXDzA==", + "dependencies": {} + }, "type-fest@0.21.3": { "integrity": "sha512-t0rzBq87m3fVcduHDUFhKmyyX+9eo6WQjZvf51Ea/M0Q7+T374Jp1aUiyUl0GKxp8M/OETVHSDvmkyPgvX+X2w==", "dependencies": {} diff --git a/openapitools.json b/openapitools.json index 7db40de..734297f 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.9.0-20240922.165752-71", + "version": "7.9.0-20241007.123707-126", "repository": { "downloadUrl": "https://oss.sonatype.org/content/repositories/snapshots/org/openapitools/openapi-generator-cli/7.9.0-SNAPSHOT/openapi-generator-cli-${versionName}.jar" }, diff --git a/src/.gitattributes b/src/.gitattributes deleted file mode 100644 index 0da4db3..0000000 --- a/src/.gitattributes +++ /dev/null @@ -1 +0,0 @@ -v2/generated/** linguist-generated diff --git a/src/v2/generated/.gitattributes b/src/v2/generated/.gitattributes new file mode 100644 index 0000000..7bf5a17 --- /dev/null +++ b/src/v2/generated/.gitattributes @@ -0,0 +1,8 @@ +**/* linguist-generated +*.md linguist-documentation + +.gitattributes text +.gitattributes export-ignore + +.gitignore text +.gitignore export-ignore diff --git a/src/v2/generated/.openapi-generator/FILES b/src/v2/generated/.openapi-generator/FILES index 9c06d1f..f129fed 100644 --- a/src/v2/generated/.openapi-generator/FILES +++ b/src/v2/generated/.openapi-generator/FILES @@ -1,3 +1,4 @@ +.gitattributes .gitignore .openapi-generator-ignore AuthApi.md @@ -89,6 +90,7 @@ models/Tenant.ts models/TextValue.ts models/TextsValue.ts models/UnprocessableEntityError.ts +models/UnsupportedMediaTypeError.ts models/User.ts models/ValidationError.ts models/ValidationErrors.ts diff --git a/src/v2/generated/AuthApi.md b/src/v2/generated/AuthApi.md index 7b43590..ccb7b1f 100644 --- a/src/v2/generated/AuthApi.md +++ b/src/v2/generated/AuthApi.md @@ -16,17 +16,15 @@ Returns metadata about the current user. ```typescript -import { } from ''; -import * as fs from 'fs'; +import { createConfiguration, AuthApi } from ''; -const configuration = .createConfiguration(); -const apiInstance = new .AuthApi(configuration); +const configuration = createConfiguration(); +const apiInstance = new AuthApi(configuration); -let body:any = {}; +const request = {}; -apiInstance.getV2AuthWhoami(body).then((data:any) => { - console.log('API called successfully. Returned data: ' + data); -}).catch((error:any) => console.error(error)); +const data = await apiInstance.getV2AuthWhoami(request); +console.log('API called successfully. Returned data:', data); ``` diff --git a/src/v2/generated/CompaniesApi.md b/src/v2/generated/CompaniesApi.md index e37c171..efc0c22 100644 --- a/src/v2/generated/CompaniesApi.md +++ b/src/v2/generated/CompaniesApi.md @@ -20,34 +20,33 @@ Paginate through Companies in Affinity. Returns basic information and non-list-s ```typescript -import { } from ''; -import * as fs from 'fs'; +import { createConfiguration, CompaniesApi } from ''; +import type { CompaniesApiGetV2CompaniesRequest } from ''; -const configuration = .createConfiguration(); -const apiInstance = new .CompaniesApi(configuration); +const configuration = createConfiguration(); +const apiInstance = new CompaniesApi(configuration); -let body:.CompaniesApiGetV2CompaniesRequest = { - // string | Cursor for the next or previous page (optional) +const request: CompaniesApiGetV2CompaniesRequest = { + // Cursor for the next or previous page (optional) cursor: "cursor_example", - // number | Number of items to include in the page (optional) + // Number of items to include in the page (optional) limit: 100, - // Array | Company IDs (optional) + // Company IDs (optional) ids: [ 1, ], - // Array | Field IDs for which to return field data (optional) + // Field IDs for which to return field data (optional) fieldIds: [ "fieldIds_example", ], - // Array<'enriched' | 'global' | 'relationship-intelligence'> | Field Types for which to return field data (optional) + // Field Types for which to return field data (optional) fieldTypes: [ "enriched", ], }; -apiInstance.getV2Companies(body).then((data:any) => { - console.log('API called successfully. Returned data: ' + data); -}).catch((error:any) => console.error(error)); +const data = await apiInstance.getV2Companies(request); +console.log('API called successfully. Returned data:', data); ``` @@ -94,22 +93,21 @@ Returns metadata on non-list-specific Company Fields. Use the returned Field ID ```typescript -import { } from ''; -import * as fs from 'fs'; +import { createConfiguration, CompaniesApi } from ''; +import type { CompaniesApiGetV2CompaniesFieldsRequest } from ''; -const configuration = .createConfiguration(); -const apiInstance = new .CompaniesApi(configuration); +const configuration = createConfiguration(); +const apiInstance = new CompaniesApi(configuration); -let body:.CompaniesApiGetV2CompaniesFieldsRequest = { - // string | Cursor for the next or previous page (optional) +const request: CompaniesApiGetV2CompaniesFieldsRequest = { + // Cursor for the next or previous page (optional) cursor: "cursor_example", - // number | Number of items to include in the page (optional) + // Number of items to include in the page (optional) limit: 100, }; -apiInstance.getV2CompaniesFields(body).then((data:any) => { - console.log('API called successfully. Returned data: ' + data); -}).catch((error:any) => console.error(error)); +const data = await apiInstance.getV2CompaniesFields(request); +console.log('API called successfully. Returned data:', data); ``` @@ -152,28 +150,27 @@ Returns basic information and non-list-specific field data on the requested Comp ```typescript -import { } from ''; -import * as fs from 'fs'; +import { createConfiguration, CompaniesApi } from ''; +import type { CompaniesApiGetV2CompaniesIdRequest } from ''; -const configuration = .createConfiguration(); -const apiInstance = new .CompaniesApi(configuration); +const configuration = createConfiguration(); +const apiInstance = new CompaniesApi(configuration); -let body:.CompaniesApiGetV2CompaniesIdRequest = { - // number | Company ID +const request: CompaniesApiGetV2CompaniesIdRequest = { + // Company ID id: 1, - // Array | Field IDs for which to return field data (optional) + // Field IDs for which to return field data (optional) fieldIds: [ "fieldIds_example", ], - // Array<'enriched' | 'global' | 'relationship-intelligence'> | Field Types for which to return field data (optional) + // Field Types for which to return field data (optional) fieldTypes: [ "enriched", ], }; -apiInstance.getV2CompaniesId(body).then((data:any) => { - console.log('API called successfully. Returned data: ' + data); -}).catch((error:any) => console.error(error)); +const data = await apiInstance.getV2CompaniesId(request); +console.log('API called successfully. Returned data:', data); ``` @@ -219,24 +216,23 @@ Paginate through the List Entries (AKA rows) for the given Company across all Li ```typescript -import { } from ''; -import * as fs from 'fs'; +import { createConfiguration, CompaniesApi } from ''; +import type { CompaniesApiGetV2CompaniesIdListEntriesRequest } from ''; -const configuration = .createConfiguration(); -const apiInstance = new .CompaniesApi(configuration); +const configuration = createConfiguration(); +const apiInstance = new CompaniesApi(configuration); -let body:.CompaniesApiGetV2CompaniesIdListEntriesRequest = { - // number | Company ID +const request: CompaniesApiGetV2CompaniesIdListEntriesRequest = { + // Company ID id: 1, - // string | Cursor for the next or previous page (optional) + // Cursor for the next or previous page (optional) cursor: "cursor_example", - // number | Number of items to include in the page (optional) + // Number of items to include in the page (optional) limit: 100, }; -apiInstance.getV2CompaniesIdListEntries(body).then((data:any) => { - console.log('API called successfully. Returned data: ' + data); -}).catch((error:any) => console.error(error)); +const data = await apiInstance.getV2CompaniesIdListEntries(request); +console.log('API called successfully. Returned data:', data); ``` @@ -282,24 +278,23 @@ Returns metadata for all the Lists on which the given Company appears. ```typescript -import { } from ''; -import * as fs from 'fs'; +import { createConfiguration, CompaniesApi } from ''; +import type { CompaniesApiGetV2CompaniesIdListsRequest } from ''; -const configuration = .createConfiguration(); -const apiInstance = new .CompaniesApi(configuration); +const configuration = createConfiguration(); +const apiInstance = new CompaniesApi(configuration); -let body:.CompaniesApiGetV2CompaniesIdListsRequest = { - // number | Company ID +const request: CompaniesApiGetV2CompaniesIdListsRequest = { + // Company ID id: 1, - // string | Cursor for the next or previous page (optional) + // Cursor for the next or previous page (optional) cursor: "cursor_example", - // number | Number of items to include in the page (optional) + // Number of items to include in the page (optional) limit: 100, }; -apiInstance.getV2CompaniesIdLists(body).then((data:any) => { - console.log('API called successfully. Returned data: ' + data); -}).catch((error:any) => console.error(error)); +const data = await apiInstance.getV2CompaniesIdLists(request); +console.log('API called successfully. Returned data:', data); ``` diff --git a/src/v2/generated/ListsApi.md b/src/v2/generated/ListsApi.md index 7ba7739..afec5fc 100644 --- a/src/v2/generated/ListsApi.md +++ b/src/v2/generated/ListsApi.md @@ -22,22 +22,21 @@ Returns metadata on Lists. ```typescript -import { } from ''; -import * as fs from 'fs'; +import { createConfiguration, ListsApi } from ''; +import type { ListsApiGetV2ListsRequest } from ''; -const configuration = .createConfiguration(); -const apiInstance = new .ListsApi(configuration); +const configuration = createConfiguration(); +const apiInstance = new ListsApi(configuration); -let body:.ListsApiGetV2ListsRequest = { - // string | Cursor for the next or previous page (optional) +const request: ListsApiGetV2ListsRequest = { + // Cursor for the next or previous page (optional) cursor: "cursor_example", - // number | Number of items to include in the page (optional) + // Number of items to include in the page (optional) limit: 100, }; -apiInstance.getV2Lists(body).then((data:any) => { - console.log('API called successfully. Returned data: ' + data); -}).catch((error:any) => console.error(error)); +const data = await apiInstance.getV2Lists(request); +console.log('API called successfully. Returned data:', data); ``` @@ -80,20 +79,19 @@ Returns metadata on a single List. ```typescript -import { } from ''; -import * as fs from 'fs'; +import { createConfiguration, ListsApi } from ''; +import type { ListsApiGetV2ListsListidRequest } from ''; -const configuration = .createConfiguration(); -const apiInstance = new .ListsApi(configuration); +const configuration = createConfiguration(); +const apiInstance = new ListsApi(configuration); -let body:.ListsApiGetV2ListsListidRequest = { - // number | List ID +const request: ListsApiGetV2ListsListidRequest = { + // List ID listId: 1, }; -apiInstance.getV2ListsListid(body).then((data:any) => { - console.log('API called successfully. Returned data: ' + data); -}).catch((error:any) => console.error(error)); +const data = await apiInstance.getV2ListsListid(request); +console.log('API called successfully. Returned data:', data); ``` @@ -136,24 +134,23 @@ Returns metadata on the Fields available on a single List. Use the returned Fie ```typescript -import { } from ''; -import * as fs from 'fs'; +import { createConfiguration, ListsApi } from ''; +import type { ListsApiGetV2ListsListidFieldsRequest } from ''; -const configuration = .createConfiguration(); -const apiInstance = new .ListsApi(configuration); +const configuration = createConfiguration(); +const apiInstance = new ListsApi(configuration); -let body:.ListsApiGetV2ListsListidFieldsRequest = { - // number | List ID +const request: ListsApiGetV2ListsListidFieldsRequest = { + // List ID listId: 1, - // string | Cursor for the next or previous page (optional) + // Cursor for the next or previous page (optional) cursor: "cursor_example", - // number | Number of items to include in the page (optional) + // Number of items to include in the page (optional) limit: 100, }; -apiInstance.getV2ListsListidFields(body).then((data:any) => { - console.log('API called successfully. Returned data: ' + data); -}).catch((error:any) => console.error(error)); +const data = await apiInstance.getV2ListsListidFields(request); +console.log('API called successfully. Returned data:', data); ``` @@ -198,32 +195,31 @@ Paginate through the List Entries (AKA rows) on a given List. Returns basic info ```typescript -import { } from ''; -import * as fs from 'fs'; +import { createConfiguration, ListsApi } from ''; +import type { ListsApiGetV2ListsListidListEntriesRequest } from ''; -const configuration = .createConfiguration(); -const apiInstance = new .ListsApi(configuration); +const configuration = createConfiguration(); +const apiInstance = new ListsApi(configuration); -let body:.ListsApiGetV2ListsListidListEntriesRequest = { - // number | List ID +const request: ListsApiGetV2ListsListidListEntriesRequest = { + // List ID listId: 1, - // string | Cursor for the next or previous page (optional) + // Cursor for the next or previous page (optional) cursor: "cursor_example", - // number | Number of items to include in the page (optional) + // Number of items to include in the page (optional) limit: 100, - // Array | Field IDs for which to return field data (optional) + // Field IDs for which to return field data (optional) fieldIds: [ "fieldIds_example", ], - // Array<'enriched' | 'global' | 'list' | 'relationship-intelligence'> | Field Types for which to return field data (optional) + // Field Types for which to return field data (optional) fieldTypes: [ "enriched", ], }; -apiInstance.getV2ListsListidListEntries(body).then((data:any) => { - console.log('API called successfully. Returned data: ' + data); -}).catch((error:any) => console.error(error)); +const data = await apiInstance.getV2ListsListidListEntries(request); +console.log('API called successfully. Returned data:', data); ``` @@ -271,24 +267,23 @@ Returns metadata on the Saved Views on a List. ```typescript -import { } from ''; -import * as fs from 'fs'; +import { createConfiguration, ListsApi } from ''; +import type { ListsApiGetV2ListsListidSavedViewsRequest } from ''; -const configuration = .createConfiguration(); -const apiInstance = new .ListsApi(configuration); +const configuration = createConfiguration(); +const apiInstance = new ListsApi(configuration); -let body:.ListsApiGetV2ListsListidSavedViewsRequest = { - // number | List ID +const request: ListsApiGetV2ListsListidSavedViewsRequest = { + // List ID listId: 1, - // string | Cursor for the next or previous page (optional) + // Cursor for the next or previous page (optional) cursor: "cursor_example", - // number | Number of items to include in the page (optional) + // Number of items to include in the page (optional) limit: 100, }; -apiInstance.getV2ListsListidSavedViews(body).then((data:any) => { - console.log('API called successfully. Returned data: ' + data); -}).catch((error:any) => console.error(error)); +const data = await apiInstance.getV2ListsListidSavedViews(request); +console.log('API called successfully. Returned data:', data); ``` @@ -333,22 +328,21 @@ Returns metadata on a single Saved View. ```typescript -import { } from ''; -import * as fs from 'fs'; +import { createConfiguration, ListsApi } from ''; +import type { ListsApiGetV2ListsListidSavedViewsViewidRequest } from ''; -const configuration = .createConfiguration(); -const apiInstance = new .ListsApi(configuration); +const configuration = createConfiguration(); +const apiInstance = new ListsApi(configuration); -let body:.ListsApiGetV2ListsListidSavedViewsViewidRequest = { - // number | List ID +const request: ListsApiGetV2ListsListidSavedViewsViewidRequest = { + // List ID listId: 1, - // number | Saved view ID + // Saved view ID viewId: 1, }; -apiInstance.getV2ListsListidSavedViewsViewid(body).then((data:any) => { - console.log('API called successfully. Returned data: ' + data); -}).catch((error:any) => console.error(error)); +const data = await apiInstance.getV2ListsListidSavedViewsViewid(request); +console.log('API called successfully. Returned data:', data); ``` @@ -392,26 +386,25 @@ Paginate through the List Entries (AKA rows) on a given Saved View. Use this end ```typescript -import { } from ''; -import * as fs from 'fs'; +import { createConfiguration, ListsApi } from ''; +import type { ListsApiGetV2ListsListidSavedViewsViewidListEntriesRequest } from ''; -const configuration = .createConfiguration(); -const apiInstance = new .ListsApi(configuration); +const configuration = createConfiguration(); +const apiInstance = new ListsApi(configuration); -let body:.ListsApiGetV2ListsListidSavedViewsViewidListEntriesRequest = { - // number | List ID +const request: ListsApiGetV2ListsListidSavedViewsViewidListEntriesRequest = { + // List ID listId: 1, - // number | Saved view ID + // Saved view ID viewId: 1, - // string | Cursor for the next or previous page (optional) + // Cursor for the next or previous page (optional) cursor: "cursor_example", - // number | Number of items to include in the page (optional) + // Number of items to include in the page (optional) limit: 100, }; -apiInstance.getV2ListsListidSavedViewsViewidListEntries(body).then((data:any) => { - console.log('API called successfully. Returned data: ' + data); -}).catch((error:any) => console.error(error)); +const data = await apiInstance.getV2ListsListidSavedViewsViewidListEntries(request); +console.log('API called successfully. Returned data:', data); ``` diff --git a/src/v2/generated/OpportunitiesApi.md b/src/v2/generated/OpportunitiesApi.md index 7b1912b..f9612d2 100644 --- a/src/v2/generated/OpportunitiesApi.md +++ b/src/v2/generated/OpportunitiesApi.md @@ -17,26 +17,25 @@ Paginate through Opportunities in Affinity. Returns basic information but **not* ```typescript -import { } from ''; -import * as fs from 'fs'; +import { createConfiguration, OpportunitiesApi } from ''; +import type { OpportunitiesApiGetV2OpportunitiesRequest } from ''; -const configuration = .createConfiguration(); -const apiInstance = new .OpportunitiesApi(configuration); +const configuration = createConfiguration(); +const apiInstance = new OpportunitiesApi(configuration); -let body:.OpportunitiesApiGetV2OpportunitiesRequest = { - // string | Cursor for the next or previous page (optional) +const request: OpportunitiesApiGetV2OpportunitiesRequest = { + // Cursor for the next or previous page (optional) cursor: "cursor_example", - // number | Number of items to include in the page (optional) + // Number of items to include in the page (optional) limit: 100, - // Array | Opportunity IDs (optional) + // Opportunity IDs (optional) ids: [ 1, ], }; -apiInstance.getV2Opportunities(body).then((data:any) => { - console.log('API called successfully. Returned data: ' + data); -}).catch((error:any) => console.error(error)); +const data = await apiInstance.getV2Opportunities(request); +console.log('API called successfully. Returned data:', data); ``` @@ -81,20 +80,19 @@ Returns basic information but **not** field data on the requested Opportunity. ```typescript -import { } from ''; -import * as fs from 'fs'; +import { createConfiguration, OpportunitiesApi } from ''; +import type { OpportunitiesApiGetV2OpportunitiesIdRequest } from ''; -const configuration = .createConfiguration(); -const apiInstance = new .OpportunitiesApi(configuration); +const configuration = createConfiguration(); +const apiInstance = new OpportunitiesApi(configuration); -let body:.OpportunitiesApiGetV2OpportunitiesIdRequest = { - // number | Opportunity ID +const request: OpportunitiesApiGetV2OpportunitiesIdRequest = { + // Opportunity ID id: 1, }; -apiInstance.getV2OpportunitiesId(body).then((data:any) => { - console.log('API called successfully. Returned data: ' + data); -}).catch((error:any) => console.error(error)); +const data = await apiInstance.getV2OpportunitiesId(request); +console.log('API called successfully. Returned data:', data); ``` diff --git a/src/v2/generated/PersonsApi.md b/src/v2/generated/PersonsApi.md index 9c99a3b..8d6b2f0 100644 --- a/src/v2/generated/PersonsApi.md +++ b/src/v2/generated/PersonsApi.md @@ -20,34 +20,33 @@ Paginate through Persons in Affinity. Returns basic information and non-list-spe ```typescript -import { } from ''; -import * as fs from 'fs'; +import { createConfiguration, PersonsApi } from ''; +import type { PersonsApiGetV2PersonsRequest } from ''; -const configuration = .createConfiguration(); -const apiInstance = new .PersonsApi(configuration); +const configuration = createConfiguration(); +const apiInstance = new PersonsApi(configuration); -let body:.PersonsApiGetV2PersonsRequest = { - // string | Cursor for the next or previous page (optional) +const request: PersonsApiGetV2PersonsRequest = { + // Cursor for the next or previous page (optional) cursor: "cursor_example", - // number | Number of items to include in the page (optional) + // Number of items to include in the page (optional) limit: 100, - // Array | People IDs (optional) + // People IDs (optional) ids: [ 1, ], - // Array | Field IDs for which to return field data (optional) + // Field IDs for which to return field data (optional) fieldIds: [ "fieldIds_example", ], - // Array<'enriched' | 'global' | 'relationship-intelligence'> | Field Types for which to return field data (optional) + // Field Types for which to return field data (optional) fieldTypes: [ "enriched", ], }; -apiInstance.getV2Persons(body).then((data:any) => { - console.log('API called successfully. Returned data: ' + data); -}).catch((error:any) => console.error(error)); +const data = await apiInstance.getV2Persons(request); +console.log('API called successfully. Returned data:', data); ``` @@ -94,22 +93,21 @@ Returns metadata on non-list-specific Person Fields. Use the returned Field IDs ```typescript -import { } from ''; -import * as fs from 'fs'; +import { createConfiguration, PersonsApi } from ''; +import type { PersonsApiGetV2PersonsFieldsRequest } from ''; -const configuration = .createConfiguration(); -const apiInstance = new .PersonsApi(configuration); +const configuration = createConfiguration(); +const apiInstance = new PersonsApi(configuration); -let body:.PersonsApiGetV2PersonsFieldsRequest = { - // string | Cursor for the next or previous page (optional) +const request: PersonsApiGetV2PersonsFieldsRequest = { + // Cursor for the next or previous page (optional) cursor: "cursor_example", - // number | Number of items to include in the page (optional) + // Number of items to include in the page (optional) limit: 100, }; -apiInstance.getV2PersonsFields(body).then((data:any) => { - console.log('API called successfully. Returned data: ' + data); -}).catch((error:any) => console.error(error)); +const data = await apiInstance.getV2PersonsFields(request); +console.log('API called successfully. Returned data:', data); ``` @@ -152,28 +150,27 @@ Returns basic information and non-list-specific field data on the requested Pers ```typescript -import { } from ''; -import * as fs from 'fs'; +import { createConfiguration, PersonsApi } from ''; +import type { PersonsApiGetV2PersonsIdRequest } from ''; -const configuration = .createConfiguration(); -const apiInstance = new .PersonsApi(configuration); +const configuration = createConfiguration(); +const apiInstance = new PersonsApi(configuration); -let body:.PersonsApiGetV2PersonsIdRequest = { - // number | Person ID +const request: PersonsApiGetV2PersonsIdRequest = { + // Person ID id: 1, - // Array | Field IDs for which to return field data (optional) + // Field IDs for which to return field data (optional) fieldIds: [ "fieldIds_example", ], - // Array<'enriched' | 'global' | 'relationship-intelligence'> | Field Types for which to return field data (optional) + // Field Types for which to return field data (optional) fieldTypes: [ "enriched", ], }; -apiInstance.getV2PersonsId(body).then((data:any) => { - console.log('API called successfully. Returned data: ' + data); -}).catch((error:any) => console.error(error)); +const data = await apiInstance.getV2PersonsId(request); +console.log('API called successfully. Returned data:', data); ``` @@ -219,24 +216,23 @@ Paginate through the List Entries (AKA rows) for the given Person across all Lis ```typescript -import { } from ''; -import * as fs from 'fs'; +import { createConfiguration, PersonsApi } from ''; +import type { PersonsApiGetV2PersonsIdListEntriesRequest } from ''; -const configuration = .createConfiguration(); -const apiInstance = new .PersonsApi(configuration); +const configuration = createConfiguration(); +const apiInstance = new PersonsApi(configuration); -let body:.PersonsApiGetV2PersonsIdListEntriesRequest = { - // number | Persons ID +const request: PersonsApiGetV2PersonsIdListEntriesRequest = { + // Persons ID id: 1, - // string | Cursor for the next or previous page (optional) + // Cursor for the next or previous page (optional) cursor: "cursor_example", - // number | Number of items to include in the page (optional) + // Number of items to include in the page (optional) limit: 100, }; -apiInstance.getV2PersonsIdListEntries(body).then((data:any) => { - console.log('API called successfully. Returned data: ' + data); -}).catch((error:any) => console.error(error)); +const data = await apiInstance.getV2PersonsIdListEntries(request); +console.log('API called successfully. Returned data:', data); ``` @@ -282,24 +278,23 @@ Returns metadata for all the Lists on which the given Person appears. ```typescript -import { } from ''; -import * as fs from 'fs'; +import { createConfiguration, PersonsApi } from ''; +import type { PersonsApiGetV2PersonsIdListsRequest } from ''; -const configuration = .createConfiguration(); -const apiInstance = new .PersonsApi(configuration); +const configuration = createConfiguration(); +const apiInstance = new PersonsApi(configuration); -let body:.PersonsApiGetV2PersonsIdListsRequest = { - // number | Persons ID +const request: PersonsApiGetV2PersonsIdListsRequest = { + // Persons ID id: 1, - // string | Cursor for the next or previous page (optional) + // Cursor for the next or previous page (optional) cursor: "cursor_example", - // number | Number of items to include in the page (optional) + // Number of items to include in the page (optional) limit: 100, }; -apiInstance.getV2PersonsIdLists(body).then((data:any) => { - console.log('API called successfully. Returned data: ' + data); -}).catch((error:any) => console.error(error)); +const data = await apiInstance.getV2PersonsIdLists(request); +console.log('API called successfully. Returned data:', data); ``` diff --git a/src/v2/generated/http/http.ts b/src/v2/generated/http/http.ts index 8c54103..231a58d 100644 --- a/src/v2/generated/http/http.ts +++ b/src/v2/generated/http/http.ts @@ -32,6 +32,8 @@ export class HttpException extends Error { */ export type RequestBody = undefined | string | FormData | URLSearchParams; +type Headers = Record; + function ensureAbsoluteUrl(url: string) { if (url.startsWith("http://") || url.startsWith("https://")) { return url; @@ -43,7 +45,7 @@ function ensureAbsoluteUrl(url: string) { * Represents an HTTP request context */ export class RequestContext { - private headers: { [key: string]: string } = {}; + private headers: Headers = {}; private body: RequestBody = undefined; private url: URL; @@ -92,7 +94,7 @@ export class RequestContext { return this.httpMethod; } - public getHeaders(): { [key: string]: string } { + public getHeaders(): Headers { return this.headers; } @@ -148,7 +150,7 @@ export class SelfDecodingBody implements ResponseBody { export class ResponseContext { public constructor( public httpStatusCode: number, - public headers: { [key: string]: string }, + public headers: Headers, public body: ResponseBody ) {} @@ -159,8 +161,8 @@ export class ResponseContext { * Parameter names are converted to lower case * The first parameter is returned with the key `""` */ - public getParsedHeader(headerName: string): { [parameter: string]: string } { - const result: { [parameter: string]: string } = {}; + public getParsedHeader(headerName: string): Headers { + const result: Headers = {}; if (!this.headers[headerName]) { return result; } @@ -233,7 +235,7 @@ export function wrapHttpLibrary(promiseHttpLibrary: PromiseHttpLibrary): HttpLib export class HttpInfo extends ResponseContext { public constructor( public httpStatusCode: number, - public headers: { [key: string]: string }, + public headers: Headers, public body: ResponseBody, public data: T, ) { diff --git a/src/v2/generated/models/AuthenticationError.ts b/src/v2/generated/models/AuthenticationError.ts index a24c1c3..77e386c 100644 --- a/src/v2/generated/models/AuthenticationError.ts +++ b/src/v2/generated/models/AuthenticationError.ts @@ -16,7 +16,7 @@ export class AuthenticationError { /** * Error code */ - 'code': string; + 'code': AuthenticationErrorCodeEnum; /** * Error message */ @@ -30,7 +30,7 @@ export class AuthenticationError { { "name": "code", "baseName": "code", - "type": "string", + "type": "AuthenticationErrorCodeEnum", "format": "" }, { @@ -47,3 +47,8 @@ export class AuthenticationError { public constructor() { } } + +export enum AuthenticationErrorCodeEnum { + Authentication = 'authentication' +} + diff --git a/src/v2/generated/models/AuthorizationError.ts b/src/v2/generated/models/AuthorizationError.ts index 43a2b27..be95b91 100644 --- a/src/v2/generated/models/AuthorizationError.ts +++ b/src/v2/generated/models/AuthorizationError.ts @@ -16,7 +16,7 @@ export class AuthorizationError { /** * Error code */ - 'code': string; + 'code': AuthorizationErrorCodeEnum; /** * Error message */ @@ -30,7 +30,7 @@ export class AuthorizationError { { "name": "code", "baseName": "code", - "type": "string", + "type": "AuthorizationErrorCodeEnum", "format": "" }, { @@ -47,3 +47,8 @@ export class AuthorizationError { public constructor() { } } + +export enum AuthorizationErrorCodeEnum { + Authorization = 'authorization' +} + diff --git a/src/v2/generated/models/BadRequestError.ts b/src/v2/generated/models/BadRequestError.ts index cde7313..37166a3 100644 --- a/src/v2/generated/models/BadRequestError.ts +++ b/src/v2/generated/models/BadRequestError.ts @@ -16,7 +16,7 @@ export class BadRequestError { /** * Error code */ - 'code': string; + 'code': BadRequestErrorCodeEnum; /** * Error message */ @@ -30,7 +30,7 @@ export class BadRequestError { { "name": "code", "baseName": "code", - "type": "string", + "type": "BadRequestErrorCodeEnum", "format": "" }, { @@ -47,3 +47,8 @@ export class BadRequestError { public constructor() { } } + +export enum BadRequestErrorCodeEnum { + BadRequest = 'bad-request' +} + diff --git a/src/v2/generated/models/ChatMessage.ts b/src/v2/generated/models/ChatMessage.ts index ad00779..4d68ad0 100644 --- a/src/v2/generated/models/ChatMessage.ts +++ b/src/v2/generated/models/ChatMessage.ts @@ -17,7 +17,7 @@ export class ChatMessage { /** * The type of interaction */ - 'type': string; + 'type': ChatMessageTypeEnum; /** * The chat message\'s unique identifier */ @@ -44,7 +44,7 @@ export class ChatMessage { { "name": "type", "baseName": "type", - "type": "string", + "type": "ChatMessageTypeEnum", "format": "" }, { @@ -86,6 +86,9 @@ export class ChatMessage { } } +export enum ChatMessageTypeEnum { + ChatMessage = 'chat-message' +} export enum ChatMessageDirectionEnum { Received = 'received', Sent = 'sent' diff --git a/src/v2/generated/models/CompaniesValue.ts b/src/v2/generated/models/CompaniesValue.ts index bee377d..5a14061 100644 --- a/src/v2/generated/models/CompaniesValue.ts +++ b/src/v2/generated/models/CompaniesValue.ts @@ -17,11 +17,11 @@ export class CompaniesValue { /** * The type of value */ - 'type': string; + 'type': CompaniesValueTypeEnum; /** * The values for many companies */ - 'data': Array; + 'data': Array | null; static readonly discriminator: string | undefined = undefined; @@ -31,7 +31,7 @@ export class CompaniesValue { { "name": "type", "baseName": "type", - "type": "string", + "type": "CompaniesValueTypeEnum", "format": "" }, { @@ -48,3 +48,8 @@ export class CompaniesValue { public constructor() { } } + +export enum CompaniesValueTypeEnum { + CompanyMulti = 'company-multi' +} + diff --git a/src/v2/generated/models/CompanyListEntry.ts b/src/v2/generated/models/CompanyListEntry.ts index 444fa01..0a50930 100644 --- a/src/v2/generated/models/CompanyListEntry.ts +++ b/src/v2/generated/models/CompanyListEntry.ts @@ -21,7 +21,7 @@ export class CompanyListEntry { /** * The entity type for this list entry */ - 'type': string; + 'type': CompanyListEntryTypeEnum; /** * The date that the list entry was created */ @@ -46,7 +46,7 @@ export class CompanyListEntry { { "name": "type", "baseName": "type", - "type": "string", + "type": "CompanyListEntryTypeEnum", "format": "" }, { @@ -75,3 +75,8 @@ export class CompanyListEntry { public constructor() { } } + +export enum CompanyListEntryTypeEnum { + Company = 'company' +} + diff --git a/src/v2/generated/models/CompanyValue.ts b/src/v2/generated/models/CompanyValue.ts index aaa1fa8..1798023 100644 --- a/src/v2/generated/models/CompanyValue.ts +++ b/src/v2/generated/models/CompanyValue.ts @@ -17,7 +17,7 @@ export class CompanyValue { /** * The type of value */ - 'type': string; + 'type': CompanyValueTypeEnum; 'data': CompanyData | null; static readonly discriminator: string | undefined = undefined; @@ -28,7 +28,7 @@ export class CompanyValue { { "name": "type", "baseName": "type", - "type": "string", + "type": "CompanyValueTypeEnum", "format": "" }, { @@ -45,3 +45,8 @@ export class CompanyValue { public constructor() { } } + +export enum CompanyValueTypeEnum { + Company = 'company' +} + diff --git a/src/v2/generated/models/ConflictError.ts b/src/v2/generated/models/ConflictError.ts index ca73e97..59dff09 100644 --- a/src/v2/generated/models/ConflictError.ts +++ b/src/v2/generated/models/ConflictError.ts @@ -16,7 +16,7 @@ export class ConflictError { /** * Error code */ - 'code': string; + 'code': ConflictErrorCodeEnum; /** * Error message */ @@ -30,7 +30,7 @@ export class ConflictError { { "name": "code", "baseName": "code", - "type": "string", + "type": "ConflictErrorCodeEnum", "format": "" }, { @@ -47,3 +47,8 @@ export class ConflictError { public constructor() { } } + +export enum ConflictErrorCodeEnum { + Conflict = 'conflict' +} + diff --git a/src/v2/generated/models/DateValue.ts b/src/v2/generated/models/DateValue.ts index 498cd5b..11f3776 100644 --- a/src/v2/generated/models/DateValue.ts +++ b/src/v2/generated/models/DateValue.ts @@ -16,7 +16,7 @@ export class DateValue { /** * The type of value */ - 'type': string; + 'type': DateValueTypeEnum; /** * The value for a date */ @@ -30,7 +30,7 @@ export class DateValue { { "name": "type", "baseName": "type", - "type": "string", + "type": "DateValueTypeEnum", "format": "" }, { @@ -47,3 +47,8 @@ export class DateValue { public constructor() { } } + +export enum DateValueTypeEnum { + Datetime = 'datetime' +} + diff --git a/src/v2/generated/models/DropdownValue.ts b/src/v2/generated/models/DropdownValue.ts index 8d0e70a..326822e 100644 --- a/src/v2/generated/models/DropdownValue.ts +++ b/src/v2/generated/models/DropdownValue.ts @@ -17,7 +17,7 @@ export class DropdownValue { /** * The type of value */ - 'type': string; + 'type': DropdownValueTypeEnum; 'data': Dropdown | null; static readonly discriminator: string | undefined = undefined; @@ -28,7 +28,7 @@ export class DropdownValue { { "name": "type", "baseName": "type", - "type": "string", + "type": "DropdownValueTypeEnum", "format": "" }, { @@ -45,3 +45,8 @@ export class DropdownValue { public constructor() { } } + +export enum DropdownValueTypeEnum { + Dropdown = 'dropdown' +} + diff --git a/src/v2/generated/models/DropdownsValue.ts b/src/v2/generated/models/DropdownsValue.ts index d053373..49aa1a9 100644 --- a/src/v2/generated/models/DropdownsValue.ts +++ b/src/v2/generated/models/DropdownsValue.ts @@ -17,11 +17,11 @@ export class DropdownsValue { /** * The type of value */ - 'type': string; + 'type': DropdownsValueTypeEnum; /** * The value for many dropdown items */ - 'data': Array; + 'data': Array | null; static readonly discriminator: string | undefined = undefined; @@ -31,7 +31,7 @@ export class DropdownsValue { { "name": "type", "baseName": "type", - "type": "string", + "type": "DropdownsValueTypeEnum", "format": "" }, { @@ -48,3 +48,8 @@ export class DropdownsValue { public constructor() { } } + +export enum DropdownsValueTypeEnum { + DropdownMulti = 'dropdown-multi' +} + diff --git a/src/v2/generated/models/Email.ts b/src/v2/generated/models/Email.ts index 37653e1..7220b8e 100644 --- a/src/v2/generated/models/Email.ts +++ b/src/v2/generated/models/Email.ts @@ -17,7 +17,7 @@ export class Email { /** * The type of interaction */ - 'type': string; + 'type': EmailTypeEnum; /** * The email\'s unique identifier */ @@ -48,7 +48,7 @@ export class Email { { "name": "type", "baseName": "type", - "type": "string", + "type": "EmailTypeEnum", "format": "" }, { @@ -95,3 +95,8 @@ export class Email { public constructor() { } } + +export enum EmailTypeEnum { + Email = 'email' +} + diff --git a/src/v2/generated/models/Field.ts b/src/v2/generated/models/Field.ts index 7aaff1c..8243ac5 100644 --- a/src/v2/generated/models/Field.ts +++ b/src/v2/generated/models/Field.ts @@ -84,7 +84,6 @@ export enum FieldTypeEnum { } export enum FieldEnrichmentSourceEnum { AffinityData = 'affinity-data', - Dealroom = 'dealroom', - Null = 'null' + Dealroom = 'dealroom' } diff --git a/src/v2/generated/models/FieldMetadata.ts b/src/v2/generated/models/FieldMetadata.ts index f81ec0f..4622f43 100644 --- a/src/v2/generated/models/FieldMetadata.ts +++ b/src/v2/generated/models/FieldMetadata.ts @@ -86,8 +86,7 @@ export enum FieldMetadataTypeEnum { } export enum FieldMetadataEnrichmentSourceEnum { AffinityData = 'affinity-data', - Dealroom = 'dealroom', - Null = 'null' + Dealroom = 'dealroom' } export enum FieldMetadataValueTypeEnum { Person = 'person', diff --git a/src/v2/generated/models/FloatValue.ts b/src/v2/generated/models/FloatValue.ts index 19d53b9..3220523 100644 --- a/src/v2/generated/models/FloatValue.ts +++ b/src/v2/generated/models/FloatValue.ts @@ -16,7 +16,7 @@ export class FloatValue { /** * The type of value */ - 'type': string; + 'type': FloatValueTypeEnum; /** * The value for a number */ @@ -30,7 +30,7 @@ export class FloatValue { { "name": "type", "baseName": "type", - "type": "string", + "type": "FloatValueTypeEnum", "format": "" }, { @@ -47,3 +47,8 @@ export class FloatValue { public constructor() { } } + +export enum FloatValueTypeEnum { + Number = 'number' +} + diff --git a/src/v2/generated/models/FloatsValue.ts b/src/v2/generated/models/FloatsValue.ts index a5d8850..b0f71cf 100644 --- a/src/v2/generated/models/FloatsValue.ts +++ b/src/v2/generated/models/FloatsValue.ts @@ -16,11 +16,11 @@ export class FloatsValue { /** * The type of value */ - 'type': string; + 'type': FloatsValueTypeEnum; /** * The value for many numbers */ - 'data': Array; + 'data': Array | null; static readonly discriminator: string | undefined = undefined; @@ -30,7 +30,7 @@ export class FloatsValue { { "name": "type", "baseName": "type", - "type": "string", + "type": "FloatsValueTypeEnum", "format": "" }, { @@ -47,3 +47,8 @@ export class FloatsValue { public constructor() { } } + +export enum FloatsValueTypeEnum { + NumberMulti = 'number-multi' +} + diff --git a/src/v2/generated/models/FormulaValue.ts b/src/v2/generated/models/FormulaValue.ts index 21dbf2d..46fbef3 100644 --- a/src/v2/generated/models/FormulaValue.ts +++ b/src/v2/generated/models/FormulaValue.ts @@ -17,7 +17,7 @@ export class FormulaValue { /** * The type of value */ - 'type': string; + 'type': FormulaValueTypeEnum; 'data': FormulaNumber | null; static readonly discriminator: string | undefined = undefined; @@ -28,7 +28,7 @@ export class FormulaValue { { "name": "type", "baseName": "type", - "type": "string", + "type": "FormulaValueTypeEnum", "format": "" }, { @@ -45,3 +45,8 @@ export class FormulaValue { public constructor() { } } + +export enum FormulaValueTypeEnum { + FormulaNumber = 'formula-number' +} + diff --git a/src/v2/generated/models/Grant.ts b/src/v2/generated/models/Grant.ts index db2a333..69866c8 100644 --- a/src/v2/generated/models/Grant.ts +++ b/src/v2/generated/models/Grant.ts @@ -16,7 +16,7 @@ export class Grant { /** * The type of grant used to authenticate */ - 'type': string; + 'type': GrantTypeEnum; /** * The scopes available to the current grant */ @@ -34,7 +34,7 @@ export class Grant { { "name": "type", "baseName": "type", - "type": "string", + "type": "GrantTypeEnum", "format": "" }, { @@ -57,3 +57,8 @@ export class Grant { public constructor() { } } + +export enum GrantTypeEnum { + ApiKey = 'api-key' +} + diff --git a/src/v2/generated/models/InteractionValue.ts b/src/v2/generated/models/InteractionValue.ts index 39c8064..3c3fad6 100644 --- a/src/v2/generated/models/InteractionValue.ts +++ b/src/v2/generated/models/InteractionValue.ts @@ -17,7 +17,7 @@ export class InteractionValue { /** * The type of value */ - 'type': string; + 'type': InteractionValueTypeEnum; 'data': Interaction | null; static readonly discriminator: string | undefined = undefined; @@ -28,7 +28,7 @@ export class InteractionValue { { "name": "type", "baseName": "type", - "type": "string", + "type": "InteractionValueTypeEnum", "format": "" }, { @@ -45,3 +45,8 @@ export class InteractionValue { public constructor() { } } + +export enum InteractionValueTypeEnum { + Interaction = 'interaction' +} + diff --git a/src/v2/generated/models/ListEntryWithEntityPaged.ts b/src/v2/generated/models/ListEntryWithEntityPaged.ts index c6afb1f..f948ad5 100644 --- a/src/v2/generated/models/ListEntryWithEntityPaged.ts +++ b/src/v2/generated/models/ListEntryWithEntityPaged.ts @@ -21,7 +21,7 @@ export class ListEntryWithEntityPaged { /** * A page of ListEntryWithEntity results */ - 'data': Array; + 'data': Array | null; 'pagination': Pagination; static readonly discriminator: string | undefined = undefined; diff --git a/src/v2/generated/models/LocationValue.ts b/src/v2/generated/models/LocationValue.ts index e5a9a37..744c164 100644 --- a/src/v2/generated/models/LocationValue.ts +++ b/src/v2/generated/models/LocationValue.ts @@ -17,7 +17,7 @@ export class LocationValue { /** * The type of value */ - 'type': string; + 'type': LocationValueTypeEnum; 'data': Location | null; static readonly discriminator: string | undefined = undefined; @@ -28,7 +28,7 @@ export class LocationValue { { "name": "type", "baseName": "type", - "type": "string", + "type": "LocationValueTypeEnum", "format": "" }, { @@ -45,3 +45,8 @@ export class LocationValue { public constructor() { } } + +export enum LocationValueTypeEnum { + Location = 'location' +} + diff --git a/src/v2/generated/models/LocationsValue.ts b/src/v2/generated/models/LocationsValue.ts index a0cbff1..60110ee 100644 --- a/src/v2/generated/models/LocationsValue.ts +++ b/src/v2/generated/models/LocationsValue.ts @@ -17,11 +17,11 @@ export class LocationsValue { /** * The type of value */ - 'type': string; + 'type': LocationsValueTypeEnum; /** * The values for many locations */ - 'data': Array; + 'data': Array | null; static readonly discriminator: string | undefined = undefined; @@ -31,7 +31,7 @@ export class LocationsValue { { "name": "type", "baseName": "type", - "type": "string", + "type": "LocationsValueTypeEnum", "format": "" }, { @@ -48,3 +48,8 @@ export class LocationsValue { public constructor() { } } + +export enum LocationsValueTypeEnum { + LocationMulti = 'location-multi' +} + diff --git a/src/v2/generated/models/Meeting.ts b/src/v2/generated/models/Meeting.ts index b52d2e9..dc738c9 100644 --- a/src/v2/generated/models/Meeting.ts +++ b/src/v2/generated/models/Meeting.ts @@ -17,7 +17,7 @@ export class Meeting { /** * The type of interaction */ - 'type': string; + 'type': MeetingTypeEnum; /** * The meeting\'s unique identifier */ @@ -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 b67c1ce..95682fd 100644 --- a/src/v2/generated/models/MethodNotAllowedError.ts +++ b/src/v2/generated/models/MethodNotAllowedError.ts @@ -16,7 +16,7 @@ export class MethodNotAllowedError { /** * Error code */ - 'code': string; + 'code': MethodNotAllowedErrorCodeEnum; /** * Error message */ @@ -30,7 +30,7 @@ export class MethodNotAllowedError { { "name": "code", "baseName": "code", - "type": "string", + "type": "MethodNotAllowedErrorCodeEnum", "format": "" }, { @@ -47,3 +47,8 @@ export class MethodNotAllowedError { public constructor() { } } + +export enum MethodNotAllowedErrorCodeEnum { + MethodNotAllowed = 'method-not-allowed' +} + diff --git a/src/v2/generated/models/NotAcceptableError.ts b/src/v2/generated/models/NotAcceptableError.ts index 85392ca..f5caa67 100644 --- a/src/v2/generated/models/NotAcceptableError.ts +++ b/src/v2/generated/models/NotAcceptableError.ts @@ -16,7 +16,7 @@ export class NotAcceptableError { /** * Error code */ - 'code': string; + 'code': NotAcceptableErrorCodeEnum; /** * Error message */ @@ -30,7 +30,7 @@ export class NotAcceptableError { { "name": "code", "baseName": "code", - "type": "string", + "type": "NotAcceptableErrorCodeEnum", "format": "" }, { @@ -47,3 +47,8 @@ export class NotAcceptableError { public constructor() { } } + +export enum NotAcceptableErrorCodeEnum { + NotAcceptable = 'not-acceptable' +} + diff --git a/src/v2/generated/models/NotFoundError.ts b/src/v2/generated/models/NotFoundError.ts index 72f82e1..38d1841 100644 --- a/src/v2/generated/models/NotFoundError.ts +++ b/src/v2/generated/models/NotFoundError.ts @@ -16,7 +16,7 @@ export class NotFoundError { /** * Error code */ - 'code': string; + 'code': NotFoundErrorCodeEnum; /** * Error message */ @@ -30,7 +30,7 @@ export class NotFoundError { { "name": "code", "baseName": "code", - "type": "string", + "type": "NotFoundErrorCodeEnum", "format": "" }, { @@ -47,3 +47,8 @@ export class NotFoundError { public constructor() { } } + +export enum NotFoundErrorCodeEnum { + NotFound = 'not-found' +} + diff --git a/src/v2/generated/models/NotImplementedError.ts b/src/v2/generated/models/NotImplementedError.ts index 8f8a595..4a1f6cd 100644 --- a/src/v2/generated/models/NotImplementedError.ts +++ b/src/v2/generated/models/NotImplementedError.ts @@ -16,7 +16,7 @@ export class NotImplementedError { /** * Error code */ - 'code': string; + 'code': NotImplementedErrorCodeEnum; /** * Error message */ @@ -30,7 +30,7 @@ export class NotImplementedError { { "name": "code", "baseName": "code", - "type": "string", + "type": "NotImplementedErrorCodeEnum", "format": "" }, { @@ -47,3 +47,8 @@ export class NotImplementedError { public constructor() { } } + +export enum NotImplementedErrorCodeEnum { + NotImplemented = 'not-implemented' +} + diff --git a/src/v2/generated/models/ObjectSerializer.ts b/src/v2/generated/models/ObjectSerializer.ts index eda4464..d2f6aa9 100644 --- a/src/v2/generated/models/ObjectSerializer.ts +++ b/src/v2/generated/models/ObjectSerializer.ts @@ -67,41 +67,42 @@ export * from '../models/Tenant.ts'; export * from '../models/TextValue.ts'; export * from '../models/TextsValue.ts'; export * from '../models/UnprocessableEntityError.ts'; +export * from '../models/UnsupportedMediaTypeError.ts'; export * from '../models/User.ts'; export * from '../models/ValidationError.ts'; export * from '../models/ValidationErrors.ts'; export * from '../models/WhoAmI.ts'; import { Attendee } from '../models/Attendee.ts'; -import { AuthenticationError } from '../models/AuthenticationError.ts'; +import { AuthenticationError, AuthenticationErrorCodeEnum } from '../models/AuthenticationError.ts'; import { AuthenticationErrors } from '../models/AuthenticationErrors.ts'; -import { AuthorizationError } from '../models/AuthorizationError.ts'; +import { AuthorizationError, AuthorizationErrorCodeEnum } from '../models/AuthorizationError.ts'; import { AuthorizationErrors } from '../models/AuthorizationErrors.ts'; -import { BadRequestError } from '../models/BadRequestError.ts'; -import { ChatMessage , ChatMessageDirectionEnum } from '../models/ChatMessage.ts'; -import { CompaniesValue } from '../models/CompaniesValue.ts'; +import { BadRequestError, BadRequestErrorCodeEnum } from '../models/BadRequestError.ts'; +import { ChatMessage, ChatMessageTypeEnum , ChatMessageDirectionEnum } from '../models/ChatMessage.ts'; +import { CompaniesValue, CompaniesValueTypeEnum } from '../models/CompaniesValue.ts'; import { Company } from '../models/Company.ts'; import { CompanyData } from '../models/CompanyData.ts'; -import { CompanyListEntry } from '../models/CompanyListEntry.ts'; +import { CompanyListEntry , CompanyListEntryTypeEnum } from '../models/CompanyListEntry.ts'; import { CompanyPaged } from '../models/CompanyPaged.ts'; -import { CompanyValue } from '../models/CompanyValue.ts'; -import { ConflictError } from '../models/ConflictError.ts'; -import { DateValue } from '../models/DateValue.ts'; +import { CompanyValue, CompanyValueTypeEnum } from '../models/CompanyValue.ts'; +import { ConflictError, ConflictErrorCodeEnum } from '../models/ConflictError.ts'; +import { DateValue, DateValueTypeEnum } from '../models/DateValue.ts'; import { Dropdown } from '../models/Dropdown.ts'; -import { DropdownValue } from '../models/DropdownValue.ts'; -import { DropdownsValue } from '../models/DropdownsValue.ts'; -import { Email } from '../models/Email.ts'; +import { DropdownValue, DropdownValueTypeEnum } from '../models/DropdownValue.ts'; +import { DropdownsValue, DropdownsValueTypeEnum } from '../models/DropdownsValue.ts'; +import { Email, EmailTypeEnum } from '../models/Email.ts'; import { Field , FieldTypeEnum , FieldEnrichmentSourceEnum } from '../models/Field.ts'; import { FieldMetadata , FieldMetadataTypeEnum , FieldMetadataEnrichmentSourceEnum , FieldMetadataValueTypeEnum } from '../models/FieldMetadata.ts'; import { FieldMetadataPaged } from '../models/FieldMetadataPaged.ts'; import { FieldValueClass } from '../models/FieldValue.ts'; -import { FloatValue } from '../models/FloatValue.ts'; -import { FloatsValue } from '../models/FloatsValue.ts'; +import { FloatValue, FloatValueTypeEnum } from '../models/FloatValue.ts'; +import { FloatsValue, FloatsValueTypeEnum } from '../models/FloatsValue.ts'; import { FormulaNumber } from '../models/FormulaNumber.ts'; -import { FormulaValue } from '../models/FormulaValue.ts'; -import { Grant } from '../models/Grant.ts'; +import { FormulaValue, FormulaValueTypeEnum } from '../models/FormulaValue.ts'; +import { Grant, GrantTypeEnum } from '../models/Grant.ts'; import { InteractionClass } from '../models/Interaction.ts'; -import { InteractionValue } from '../models/InteractionValue.ts'; +import { InteractionValue, InteractionValueTypeEnum } from '../models/InteractionValue.ts'; import { List } from '../models/List.ts'; import { ListEntry } from '../models/ListEntry.ts'; import { ListEntryPaged } from '../models/ListEntryPaged.ts'; @@ -111,38 +112,39 @@ import { ListPaged } from '../models/ListPaged.ts'; import { ListWithType , ListWithTypeTypeEnum } from '../models/ListWithType.ts'; import { ListWithTypePaged } from '../models/ListWithTypePaged.ts'; import { Location } from '../models/Location.ts'; -import { LocationValue } from '../models/LocationValue.ts'; -import { LocationsValue } from '../models/LocationsValue.ts'; -import { Meeting } from '../models/Meeting.ts'; -import { MethodNotAllowedError } from '../models/MethodNotAllowedError.ts'; -import { NotAcceptableError } from '../models/NotAcceptableError.ts'; -import { NotFoundError } from '../models/NotFoundError.ts'; +import { LocationValue, LocationValueTypeEnum } from '../models/LocationValue.ts'; +import { LocationsValue, LocationsValueTypeEnum } from '../models/LocationsValue.ts'; +import { Meeting, MeetingTypeEnum } from '../models/Meeting.ts'; +import { MethodNotAllowedError, MethodNotAllowedErrorCodeEnum } from '../models/MethodNotAllowedError.ts'; +import { NotAcceptableError, NotAcceptableErrorCodeEnum } from '../models/NotAcceptableError.ts'; +import { NotFoundError, NotFoundErrorCodeEnum } from '../models/NotFoundError.ts'; import { NotFoundErrors } from '../models/NotFoundErrors.ts'; -import { NotImplementedError } from '../models/NotImplementedError.ts'; +import { NotImplementedError, NotImplementedErrorCodeEnum } from '../models/NotImplementedError.ts'; import { Opportunity } from '../models/Opportunity.ts'; -import { OpportunityListEntry } from '../models/OpportunityListEntry.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 { Person , PersonTypeEnum } from '../models/Person.ts'; import { PersonData , PersonDataTypeEnum } from '../models/PersonData.ts'; -import { PersonListEntry } from '../models/PersonListEntry.ts'; +import { PersonListEntry , PersonListEntryTypeEnum } from '../models/PersonListEntry.ts'; import { PersonPaged } from '../models/PersonPaged.ts'; -import { PersonValue } from '../models/PersonValue.ts'; -import { PersonsValue } from '../models/PersonsValue.ts'; -import { PhoneCall } from '../models/PhoneCall.ts'; +import { PersonValue, PersonValueTypeEnum } from '../models/PersonValue.ts'; +import { PersonsValue, PersonsValueTypeEnum } from '../models/PersonsValue.ts'; +import { PhoneCall, PhoneCallTypeEnum } from '../models/PhoneCall.ts'; import { RankedDropdown } from '../models/RankedDropdown.ts'; -import { RankedDropdownValue } from '../models/RankedDropdownValue.ts'; -import { RateLimitError } from '../models/RateLimitError.ts'; +import { RankedDropdownValue, RankedDropdownValueTypeEnum } from '../models/RankedDropdownValue.ts'; +import { RateLimitError, RateLimitErrorCodeEnum } from '../models/RateLimitError.ts'; import { SavedView , SavedViewTypeEnum } from '../models/SavedView.ts'; import { SavedViewPaged } from '../models/SavedViewPaged.ts'; -import { ServerError } from '../models/ServerError.ts'; +import { ServerError, ServerErrorCodeEnum } from '../models/ServerError.ts'; import { Tenant } from '../models/Tenant.ts'; import { TextValue, TextValueTypeEnum } from '../models/TextValue.ts'; -import { TextsValue } from '../models/TextsValue.ts'; -import { UnprocessableEntityError } from '../models/UnprocessableEntityError.ts'; +import { TextsValue, TextsValueTypeEnum } from '../models/TextsValue.ts'; +import { UnprocessableEntityError, UnprocessableEntityErrorCodeEnum } from '../models/UnprocessableEntityError.ts'; +import { UnsupportedMediaTypeError, UnsupportedMediaTypeErrorCodeEnum } from '../models/UnsupportedMediaTypeError.ts'; import { User } from '../models/User.ts'; -import { ValidationError } from '../models/ValidationError.ts'; +import { ValidationError, ValidationErrorCodeEnum } from '../models/ValidationError.ts'; import { ValidationErrors } from '../models/ValidationErrors.ts'; import { WhoAmI } from '../models/WhoAmI.ts'; @@ -159,21 +161,57 @@ let primitives = [ ]; let enumsMap: Set = new Set([ + "AuthenticationErrorCodeEnum", + "AuthorizationErrorCodeEnum", + "BadRequestErrorCodeEnum", + "ChatMessageTypeEnum", "ChatMessageDirectionEnum", + "CompaniesValueTypeEnum", + "CompanyListEntryTypeEnum", + "CompanyValueTypeEnum", + "ConflictErrorCodeEnum", + "DateValueTypeEnum", + "DropdownValueTypeEnum", + "DropdownsValueTypeEnum", + "EmailTypeEnum", "FieldTypeEnum", "FieldEnrichmentSourceEnum", "FieldMetadataTypeEnum", "FieldMetadataEnrichmentSourceEnum", "FieldMetadataValueTypeEnum", "FieldValueTypeEnum", + "FloatValueTypeEnum", + "FloatsValueTypeEnum", + "FormulaValueTypeEnum", + "GrantTypeEnum", "InteractionTypeEnum", "InteractionDirectionEnum", + "InteractionValueTypeEnum", "ListEntryWithEntityTypeEnum", "ListWithTypeTypeEnum", + "LocationValueTypeEnum", + "LocationsValueTypeEnum", + "MeetingTypeEnum", + "MethodNotAllowedErrorCodeEnum", + "NotAcceptableErrorCodeEnum", + "NotFoundErrorCodeEnum", + "NotImplementedErrorCodeEnum", + "OpportunityListEntryTypeEnum", "PersonTypeEnum", "PersonDataTypeEnum", + "PersonListEntryTypeEnum", + "PersonValueTypeEnum", + "PersonsValueTypeEnum", + "PhoneCallTypeEnum", + "RankedDropdownValueTypeEnum", + "RateLimitErrorCodeEnum", "SavedViewTypeEnum", + "ServerErrorCodeEnum", "TextValueTypeEnum", + "TextsValueTypeEnum", + "UnprocessableEntityErrorCodeEnum", + "UnsupportedMediaTypeErrorCodeEnum", + "ValidationErrorCodeEnum", ]); let typeMap: {[index: string]: any} = { @@ -246,6 +284,7 @@ let typeMap: {[index: string]: any} = { "TextValue": TextValue, "TextsValue": TextsValue, "UnprocessableEntityError": UnprocessableEntityError, + "UnsupportedMediaTypeError": UnsupportedMediaTypeError, "User": User, "ValidationError": ValidationError, "ValidationErrors": ValidationErrors, @@ -304,6 +343,13 @@ const supportedMimeTypePredicatesWithPriority: MimeTypePredicate[] = [ isFormUrlencodedMimeType, ]; +const nullableSuffix = " | null"; +const optionalSuffix = " | undefined"; +const arrayPrefix = "Array<"; +const arraySuffix = ">"; +const mapPrefix = "{ [key: string]: "; +const mapSuffix = "; }"; + export class ObjectSerializer { public static findCorrectType(data: any, expectedType: string) { if (data == undefined) { @@ -343,19 +389,35 @@ export class ObjectSerializer { } } - public static serialize(data: any, type: string, format: string) { + public static serialize(data: any, type: string, format: string): any { if (data == undefined) { return data; } else if (primitives.indexOf(type.toLowerCase()) !== -1) { return data; - } else if (type.lastIndexOf("Array<", 0) === 0) { // string.startsWith pre es6 - let subType: string = type.replace("Array<", ""); // Array => Type> - subType = subType.substring(0, subType.length - 1); // Type> => Type + } else if (type.endsWith(nullableSuffix)) { + let subType: string = type.slice(0, -nullableSuffix.length); // Type | null => Type + return ObjectSerializer.serialize(data, subType, format); + } else if (type.endsWith(optionalSuffix)) { + let subType: string = type.slice(0, -optionalSuffix.length); // Type | undefined => Type + return ObjectSerializer.serialize(data, subType, format); + } else if (type.startsWith(arrayPrefix)) { + let subType: string = type.slice(arrayPrefix.length, -arraySuffix.length); // Array => Type let transformedData: any[] = []; for (let date of data) { transformedData.push(ObjectSerializer.serialize(date, subType, format)); } return transformedData; + } else if (type.startsWith(mapPrefix)) { + let subType: string = type.slice(mapPrefix.length, -mapSuffix.length); // { [key: string]: Type; } => Type + let transformedData: { [key: string]: any } = {}; + for (let key in data) { + transformedData[key] = ObjectSerializer.serialize( + data[key], + subType, + format, + ); + } + return transformedData; } else if (type === "Date") { if (format == "date") { let month = data.getMonth()+1 @@ -388,21 +450,37 @@ export class ObjectSerializer { } } - public static deserialize(data: any, type: string, format: string) { + public static deserialize(data: any, type: string, format: string): any { // polymorphism may change the actual type. type = ObjectSerializer.findCorrectType(data, type); if (data == undefined) { return data; } else if (primitives.indexOf(type.toLowerCase()) !== -1) { return data; - } else if (type.lastIndexOf("Array<", 0) === 0) { // string.startsWith pre es6 - let subType: string = type.replace("Array<", ""); // Array => Type> - subType = subType.substring(0, subType.length - 1); // Type> => Type + } else if (type.endsWith(nullableSuffix)) { + let subType: string = type.slice(0, -nullableSuffix.length); // Type | null => Type + return ObjectSerializer.deserialize(data, subType, format); + } else if (type.endsWith(optionalSuffix)) { + let subType: string = type.slice(0, -optionalSuffix.length); // Type | undefined => Type + return ObjectSerializer.deserialize(data, subType, format); + } else if (type.startsWith(arrayPrefix)) { + let subType: string = type.slice(arrayPrefix.length, -arraySuffix.length); // Array => Type let transformedData: any[] = []; for (let date of data) { transformedData.push(ObjectSerializer.deserialize(date, subType, format)); } return transformedData; + } else if (type.startsWith(mapPrefix)) { + let subType: string = type.slice(mapPrefix.length, -mapSuffix.length); // { [key: string]: Type; } => Type + let transformedData: { [key: string]: any } = {}; + for (let key in data) { + transformedData[key] = ObjectSerializer.deserialize( + data[key], + subType, + format, + ); + } + return transformedData; } else if (type === "Date") { return new Date(data); } else { diff --git a/src/v2/generated/models/OpportunityListEntry.ts b/src/v2/generated/models/OpportunityListEntry.ts index ef356d0..818f27b 100644 --- a/src/v2/generated/models/OpportunityListEntry.ts +++ b/src/v2/generated/models/OpportunityListEntry.ts @@ -21,7 +21,7 @@ export class OpportunityListEntry { /** * The entity type for this list entry */ - 'type': string; + 'type': OpportunityListEntryTypeEnum; /** * The date that the list entry was created */ @@ -46,7 +46,7 @@ export class OpportunityListEntry { { "name": "type", "baseName": "type", - "type": "string", + "type": "OpportunityListEntryTypeEnum", "format": "" }, { @@ -75,3 +75,8 @@ export class OpportunityListEntry { public constructor() { } } + +export enum OpportunityListEntryTypeEnum { + Opportunity = 'opportunity' +} + diff --git a/src/v2/generated/models/PersonListEntry.ts b/src/v2/generated/models/PersonListEntry.ts index 52b033f..9c92a40 100644 --- a/src/v2/generated/models/PersonListEntry.ts +++ b/src/v2/generated/models/PersonListEntry.ts @@ -21,7 +21,7 @@ export class PersonListEntry { /** * The entity type for this list entry */ - 'type': string; + 'type': PersonListEntryTypeEnum; /** * The date that the list entry was created */ @@ -46,7 +46,7 @@ export class PersonListEntry { { "name": "type", "baseName": "type", - "type": "string", + "type": "PersonListEntryTypeEnum", "format": "" }, { @@ -75,3 +75,8 @@ export class PersonListEntry { public constructor() { } } + +export enum PersonListEntryTypeEnum { + Person = 'person' +} + diff --git a/src/v2/generated/models/PersonValue.ts b/src/v2/generated/models/PersonValue.ts index a1d2a54..cd81d97 100644 --- a/src/v2/generated/models/PersonValue.ts +++ b/src/v2/generated/models/PersonValue.ts @@ -17,7 +17,7 @@ export class PersonValue { /** * The type of value */ - 'type': string; + 'type': PersonValueTypeEnum; 'data': PersonData | null; static readonly discriminator: string | undefined = undefined; @@ -28,7 +28,7 @@ export class PersonValue { { "name": "type", "baseName": "type", - "type": "string", + "type": "PersonValueTypeEnum", "format": "" }, { @@ -45,3 +45,8 @@ export class PersonValue { public constructor() { } } + +export enum PersonValueTypeEnum { + Person = 'person' +} + diff --git a/src/v2/generated/models/PersonsValue.ts b/src/v2/generated/models/PersonsValue.ts index 71ef10d..1075624 100644 --- a/src/v2/generated/models/PersonsValue.ts +++ b/src/v2/generated/models/PersonsValue.ts @@ -17,11 +17,11 @@ export class PersonsValue { /** * The type of value */ - 'type': string; + 'type': PersonsValueTypeEnum; /** * The values for many persons */ - 'data': Array; + 'data': Array | null; static readonly discriminator: string | undefined = undefined; @@ -31,7 +31,7 @@ export class PersonsValue { { "name": "type", "baseName": "type", - "type": "string", + "type": "PersonsValueTypeEnum", "format": "" }, { @@ -48,3 +48,8 @@ export class PersonsValue { public constructor() { } } + +export enum PersonsValueTypeEnum { + PersonMulti = 'person-multi' +} + diff --git a/src/v2/generated/models/PhoneCall.ts b/src/v2/generated/models/PhoneCall.ts index 8d4a492..3d3907a 100644 --- a/src/v2/generated/models/PhoneCall.ts +++ b/src/v2/generated/models/PhoneCall.ts @@ -17,7 +17,7 @@ export class PhoneCall { /** * The type of interaction */ - 'type': string; + 'type': PhoneCallTypeEnum; /** * The phon_call\'s unique identifier */ @@ -39,7 +39,7 @@ export class PhoneCall { { "name": "type", "baseName": "type", - "type": "string", + "type": "PhoneCallTypeEnum", "format": "" }, { @@ -68,3 +68,8 @@ export class PhoneCall { public constructor() { } } + +export enum PhoneCallTypeEnum { + Call = 'call' +} + diff --git a/src/v2/generated/models/RankedDropdownValue.ts b/src/v2/generated/models/RankedDropdownValue.ts index 16e7a25..b7589a0 100644 --- a/src/v2/generated/models/RankedDropdownValue.ts +++ b/src/v2/generated/models/RankedDropdownValue.ts @@ -17,7 +17,7 @@ export class RankedDropdownValue { /** * The type of value */ - 'type': string; + 'type': RankedDropdownValueTypeEnum; 'data': RankedDropdown | null; static readonly discriminator: string | undefined = undefined; @@ -28,7 +28,7 @@ export class RankedDropdownValue { { "name": "type", "baseName": "type", - "type": "string", + "type": "RankedDropdownValueTypeEnum", "format": "" }, { @@ -45,3 +45,8 @@ export class RankedDropdownValue { public constructor() { } } + +export enum RankedDropdownValueTypeEnum { + RankedDropdown = 'ranked-dropdown' +} + diff --git a/src/v2/generated/models/RateLimitError.ts b/src/v2/generated/models/RateLimitError.ts index 7c90d55..1123e54 100644 --- a/src/v2/generated/models/RateLimitError.ts +++ b/src/v2/generated/models/RateLimitError.ts @@ -16,7 +16,7 @@ export class RateLimitError { /** * Error code */ - 'code': string; + 'code': RateLimitErrorCodeEnum; /** * Error message */ @@ -30,7 +30,7 @@ export class RateLimitError { { "name": "code", "baseName": "code", - "type": "string", + "type": "RateLimitErrorCodeEnum", "format": "" }, { @@ -47,3 +47,8 @@ export class RateLimitError { public constructor() { } } + +export enum RateLimitErrorCodeEnum { + RateLimit = 'rate-limit' +} + diff --git a/src/v2/generated/models/ServerError.ts b/src/v2/generated/models/ServerError.ts index 6e7a54e..dfc73d5 100644 --- a/src/v2/generated/models/ServerError.ts +++ b/src/v2/generated/models/ServerError.ts @@ -16,7 +16,7 @@ export class ServerError { /** * Error code */ - 'code': string; + 'code': ServerErrorCodeEnum; /** * Error message */ @@ -30,7 +30,7 @@ export class ServerError { { "name": "code", "baseName": "code", - "type": "string", + "type": "ServerErrorCodeEnum", "format": "" }, { @@ -47,3 +47,8 @@ export class ServerError { public constructor() { } } + +export enum ServerErrorCodeEnum { + Server = 'server' +} + diff --git a/src/v2/generated/models/TextsValue.ts b/src/v2/generated/models/TextsValue.ts index efc1649..b6e8685 100644 --- a/src/v2/generated/models/TextsValue.ts +++ b/src/v2/generated/models/TextsValue.ts @@ -16,11 +16,11 @@ export class TextsValue { /** * The type of value */ - 'type': string; + 'type': TextsValueTypeEnum; /** * The value for many strings */ - 'data': Array; + 'data': Array | null; static readonly discriminator: string | undefined = undefined; @@ -30,7 +30,7 @@ export class TextsValue { { "name": "type", "baseName": "type", - "type": "string", + "type": "TextsValueTypeEnum", "format": "" }, { @@ -47,3 +47,8 @@ export class TextsValue { public constructor() { } } + +export enum TextsValueTypeEnum { + FilterableTextMulti = 'filterable-text-multi' +} + diff --git a/src/v2/generated/models/UnprocessableEntityError.ts b/src/v2/generated/models/UnprocessableEntityError.ts index 836eb16..3ce4b79 100644 --- a/src/v2/generated/models/UnprocessableEntityError.ts +++ b/src/v2/generated/models/UnprocessableEntityError.ts @@ -16,7 +16,7 @@ export class UnprocessableEntityError { /** * Error code */ - 'code': string; + 'code': UnprocessableEntityErrorCodeEnum; /** * Error message */ @@ -30,7 +30,7 @@ export class UnprocessableEntityError { { "name": "code", "baseName": "code", - "type": "string", + "type": "UnprocessableEntityErrorCodeEnum", "format": "" }, { @@ -47,3 +47,8 @@ export class UnprocessableEntityError { public constructor() { } } + +export enum UnprocessableEntityErrorCodeEnum { + UnprocessableEntity = 'unprocessable-entity' +} + diff --git a/src/v2/generated/models/UnsupportedMediaTypeError.ts b/src/v2/generated/models/UnsupportedMediaTypeError.ts new file mode 100644 index 0000000..d47337d --- /dev/null +++ b/src/v2/generated/models/UnsupportedMediaTypeError.ts @@ -0,0 +1,54 @@ +/** + * 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 ## 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: 2.0.0 + * 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 UnsupportedMediaTypeError { + /** + * Error code + */ + 'code': UnsupportedMediaTypeErrorCodeEnum; + /** + * Error message + */ + 'message': 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": "code", + "baseName": "code", + "type": "UnsupportedMediaTypeErrorCodeEnum", + "format": "" + }, + { + "name": "message", + "baseName": "message", + "type": "string", + "format": "" + } ]; + + static getAttributeTypeMap() { + return UnsupportedMediaTypeError.attributeTypeMap; + } + + public constructor() { + } +} + +export enum UnsupportedMediaTypeErrorCodeEnum { + UnsupportedMediaType = 'unsupported-media-type' +} + diff --git a/src/v2/generated/models/ValidationError.ts b/src/v2/generated/models/ValidationError.ts index 4162e56..5fd4f83 100644 --- a/src/v2/generated/models/ValidationError.ts +++ b/src/v2/generated/models/ValidationError.ts @@ -16,7 +16,7 @@ export class ValidationError { /** * Error code */ - 'code': string; + 'code': ValidationErrorCodeEnum; /** * Error message */ @@ -34,7 +34,7 @@ export class ValidationError { { "name": "code", "baseName": "code", - "type": "string", + "type": "ValidationErrorCodeEnum", "format": "" }, { @@ -57,3 +57,8 @@ export class ValidationError { public constructor() { } } + +export enum ValidationErrorCodeEnum { + Validation = 'validation' +} + diff --git a/src/v2/generated/models/all.ts b/src/v2/generated/models/all.ts index 33be023..6577a7b 100644 --- a/src/v2/generated/models/all.ts +++ b/src/v2/generated/models/all.ts @@ -67,6 +67,7 @@ export * from '../models/Tenant.ts' export * from '../models/TextValue.ts' export * from '../models/TextsValue.ts' export * from '../models/UnprocessableEntityError.ts' +export * from '../models/UnsupportedMediaTypeError.ts' export * from '../models/User.ts' export * from '../models/ValidationError.ts' export * from '../models/ValidationErrors.ts' diff --git a/src/v2/generated/types/ObjectParamAPI.ts b/src/v2/generated/types/ObjectParamAPI.ts index 69cc86a..5d6edad 100644 --- a/src/v2/generated/types/ObjectParamAPI.ts +++ b/src/v2/generated/types/ObjectParamAPI.ts @@ -70,6 +70,7 @@ import { Tenant } from '../models/Tenant.ts'; import { TextValue } from '../models/TextValue.ts'; import { TextsValue } from '../models/TextsValue.ts'; import { UnprocessableEntityError } from '../models/UnprocessableEntityError.ts'; +import { UnsupportedMediaTypeError } from '../models/UnsupportedMediaTypeError.ts'; import { User } from '../models/User.ts'; import { ValidationError } from '../models/ValidationError.ts'; import { ValidationErrors } from '../models/ValidationErrors.ts'; @@ -114,30 +115,37 @@ import { CompaniesApiRequestFactory, CompaniesApiResponseProcessor} from "../api export interface CompaniesApiGetV2CompaniesRequest { /** * Cursor for the next or previous page + * Defaults to: undefined * @type string * @memberof CompaniesApigetV2Companies */ cursor?: string /** * Number of items to include in the page + * Minimum: 1 + * Maximum: 100 + * Defaults to: 100 * @type number * @memberof CompaniesApigetV2Companies */ limit?: number /** * Company IDs + * Defaults to: undefined * @type Array<number> * @memberof CompaniesApigetV2Companies */ ids?: Array /** * Field IDs for which to return field data + * Defaults to: undefined * @type Array<string> * @memberof CompaniesApigetV2Companies */ fieldIds?: Array /** * Field Types for which to return field data + * Defaults to: undefined * @type Array<'enriched' | 'global' | 'relationship-intelligence'> * @memberof CompaniesApigetV2Companies */ @@ -147,12 +155,16 @@ export interface CompaniesApiGetV2CompaniesRequest { export interface CompaniesApiGetV2CompaniesFieldsRequest { /** * Cursor for the next or previous page + * Defaults to: undefined * @type string * @memberof CompaniesApigetV2CompaniesFields */ cursor?: string /** * Number of items to include in the page + * Minimum: 1 + * Maximum: 100 + * Defaults to: 100 * @type number * @memberof CompaniesApigetV2CompaniesFields */ @@ -162,18 +174,23 @@ export interface CompaniesApiGetV2CompaniesFieldsRequest { export interface CompaniesApiGetV2CompaniesIdRequest { /** * Company ID + * Minimum: 1 + * Maximum: -9223372036854775616 + * Defaults to: undefined * @type number * @memberof CompaniesApigetV2CompaniesId */ id: number /** * Field IDs for which to return field data + * Defaults to: undefined * @type Array<string> * @memberof CompaniesApigetV2CompaniesId */ fieldIds?: Array /** * Field Types for which to return field data + * Defaults to: undefined * @type Array<'enriched' | 'global' | 'relationship-intelligence'> * @memberof CompaniesApigetV2CompaniesId */ @@ -183,18 +200,25 @@ export interface CompaniesApiGetV2CompaniesIdRequest { export interface CompaniesApiGetV2CompaniesIdListEntriesRequest { /** * Company ID + * Minimum: 1 + * Maximum: -9223372036854775616 + * Defaults to: undefined * @type number * @memberof CompaniesApigetV2CompaniesIdListEntries */ id: number /** * Cursor for the next or previous page + * Defaults to: undefined * @type string * @memberof CompaniesApigetV2CompaniesIdListEntries */ cursor?: string /** * Number of items to include in the page + * Minimum: 1 + * Maximum: 100 + * Defaults to: 100 * @type number * @memberof CompaniesApigetV2CompaniesIdListEntries */ @@ -204,18 +228,25 @@ export interface CompaniesApiGetV2CompaniesIdListEntriesRequest { export interface CompaniesApiGetV2CompaniesIdListsRequest { /** * Company ID + * Minimum: 1 + * Maximum: -9223372036854775616 + * Defaults to: undefined * @type number * @memberof CompaniesApigetV2CompaniesIdLists */ id: number /** * Cursor for the next or previous page + * Defaults to: undefined * @type string * @memberof CompaniesApigetV2CompaniesIdLists */ cursor?: string /** * Number of items to include in the page + * Minimum: 1 + * Maximum: 100 + * Defaults to: 100 * @type number * @memberof CompaniesApigetV2CompaniesIdLists */ @@ -327,12 +358,16 @@ import { ListsApiRequestFactory, ListsApiResponseProcessor} from "../apis/ListsA export interface ListsApiGetV2ListsRequest { /** * Cursor for the next or previous page + * Defaults to: undefined * @type string * @memberof ListsApigetV2Lists */ cursor?: string /** * Number of items to include in the page + * Minimum: 1 + * Maximum: 100 + * Defaults to: 100 * @type number * @memberof ListsApigetV2Lists */ @@ -342,6 +377,9 @@ export interface ListsApiGetV2ListsRequest { export interface ListsApiGetV2ListsListidRequest { /** * List ID + * Minimum: 1 + * Maximum: -9223372036854775616 + * Defaults to: undefined * @type number * @memberof ListsApigetV2ListsListid */ @@ -351,18 +389,25 @@ export interface ListsApiGetV2ListsListidRequest { export interface ListsApiGetV2ListsListidFieldsRequest { /** * List ID + * Minimum: 1 + * Maximum: -9223372036854775616 + * Defaults to: undefined * @type number * @memberof ListsApigetV2ListsListidFields */ listId: number /** * Cursor for the next or previous page + * Defaults to: undefined * @type string * @memberof ListsApigetV2ListsListidFields */ cursor?: string /** * Number of items to include in the page + * Minimum: 1 + * Maximum: 100 + * Defaults to: 100 * @type number * @memberof ListsApigetV2ListsListidFields */ @@ -372,30 +417,39 @@ export interface ListsApiGetV2ListsListidFieldsRequest { export interface ListsApiGetV2ListsListidListEntriesRequest { /** * List ID + * Minimum: 1 + * Maximum: -9223372036854775616 + * Defaults to: undefined * @type number * @memberof ListsApigetV2ListsListidListEntries */ listId: number /** * Cursor for the next or previous page + * Defaults to: undefined * @type string * @memberof ListsApigetV2ListsListidListEntries */ cursor?: string /** * Number of items to include in the page + * Minimum: 1 + * Maximum: 100 + * Defaults to: 100 * @type number * @memberof ListsApigetV2ListsListidListEntries */ limit?: number /** * Field IDs for which to return field data + * Defaults to: undefined * @type Array<string> * @memberof ListsApigetV2ListsListidListEntries */ fieldIds?: Array /** * Field Types for which to return field data + * Defaults to: undefined * @type Array<'enriched' | 'global' | 'list' | 'relationship-intelligence'> * @memberof ListsApigetV2ListsListidListEntries */ @@ -405,18 +459,25 @@ export interface ListsApiGetV2ListsListidListEntriesRequest { export interface ListsApiGetV2ListsListidSavedViewsRequest { /** * List ID + * Minimum: 1 + * Maximum: -9223372036854775616 + * Defaults to: undefined * @type number * @memberof ListsApigetV2ListsListidSavedViews */ listId: number /** * Cursor for the next or previous page + * Defaults to: undefined * @type string * @memberof ListsApigetV2ListsListidSavedViews */ cursor?: string /** * Number of items to include in the page + * Minimum: 1 + * Maximum: 100 + * Defaults to: 100 * @type number * @memberof ListsApigetV2ListsListidSavedViews */ @@ -426,12 +487,18 @@ export interface ListsApiGetV2ListsListidSavedViewsRequest { 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 + * Defaults to: undefined * @type number * @memberof ListsApigetV2ListsListidSavedViewsViewid */ @@ -441,24 +508,34 @@ export interface ListsApiGetV2ListsListidSavedViewsViewidRequest { export interface ListsApiGetV2ListsListidSavedViewsViewidListEntriesRequest { /** * List ID + * Minimum: 1 + * Maximum: -9223372036854775616 + * Defaults to: undefined * @type number * @memberof ListsApigetV2ListsListidSavedViewsViewidListEntries */ listId: number /** * Saved view ID + * Minimum: 1 + * Maximum: -9223372036854775616 + * Defaults to: undefined * @type number * @memberof ListsApigetV2ListsListidSavedViewsViewidListEntries */ viewId: number /** * Cursor for the next or previous page + * Defaults to: undefined * @type string * @memberof ListsApigetV2ListsListidSavedViewsViewidListEntries */ cursor?: string /** * Number of items to include in the page + * Minimum: 1 + * Maximum: 100 + * Defaults to: 100 * @type number * @memberof ListsApigetV2ListsListidSavedViewsViewidListEntries */ @@ -606,18 +683,23 @@ import { OpportunitiesApiRequestFactory, OpportunitiesApiResponseProcessor} from export interface OpportunitiesApiGetV2OpportunitiesRequest { /** * Cursor for the next or previous page + * Defaults to: undefined * @type string * @memberof OpportunitiesApigetV2Opportunities */ cursor?: string /** * Number of items to include in the page + * Minimum: 1 + * Maximum: 100 + * Defaults to: 100 * @type number * @memberof OpportunitiesApigetV2Opportunities */ limit?: number /** * Opportunity IDs + * Defaults to: undefined * @type Array<number> * @memberof OpportunitiesApigetV2Opportunities */ @@ -627,6 +709,9 @@ export interface OpportunitiesApiGetV2OpportunitiesRequest { export interface OpportunitiesApiGetV2OpportunitiesIdRequest { /** * Opportunity ID + * Minimum: 1 + * Maximum: -9223372036854775616 + * Defaults to: undefined * @type number * @memberof OpportunitiesApigetV2OpportunitiesId */ @@ -684,30 +769,37 @@ import { PersonsApiRequestFactory, PersonsApiResponseProcessor} from "../apis/Pe export interface PersonsApiGetV2PersonsRequest { /** * Cursor for the next or previous page + * Defaults to: undefined * @type string * @memberof PersonsApigetV2Persons */ cursor?: string /** * Number of items to include in the page + * Minimum: 1 + * Maximum: 100 + * Defaults to: 100 * @type number * @memberof PersonsApigetV2Persons */ limit?: number /** * People IDs + * Defaults to: undefined * @type Array<number> * @memberof PersonsApigetV2Persons */ ids?: Array /** * Field IDs for which to return field data + * Defaults to: undefined * @type Array<string> * @memberof PersonsApigetV2Persons */ fieldIds?: Array /** * Field Types for which to return field data + * Defaults to: undefined * @type Array<'enriched' | 'global' | 'relationship-intelligence'> * @memberof PersonsApigetV2Persons */ @@ -717,12 +809,16 @@ export interface PersonsApiGetV2PersonsRequest { export interface PersonsApiGetV2PersonsFieldsRequest { /** * Cursor for the next or previous page + * Defaults to: undefined * @type string * @memberof PersonsApigetV2PersonsFields */ cursor?: string /** * Number of items to include in the page + * Minimum: 1 + * Maximum: 100 + * Defaults to: 100 * @type number * @memberof PersonsApigetV2PersonsFields */ @@ -732,18 +828,23 @@ export interface PersonsApiGetV2PersonsFieldsRequest { export interface PersonsApiGetV2PersonsIdRequest { /** * Person ID + * Minimum: 1 + * Maximum: -9223372036854775616 + * Defaults to: undefined * @type number * @memberof PersonsApigetV2PersonsId */ id: number /** * Field IDs for which to return field data + * Defaults to: undefined * @type Array<string> * @memberof PersonsApigetV2PersonsId */ fieldIds?: Array /** * Field Types for which to return field data + * Defaults to: undefined * @type Array<'enriched' | 'global' | 'relationship-intelligence'> * @memberof PersonsApigetV2PersonsId */ @@ -753,18 +854,25 @@ export interface PersonsApiGetV2PersonsIdRequest { export interface PersonsApiGetV2PersonsIdListEntriesRequest { /** * Persons ID + * Minimum: 1 + * Maximum: -9223372036854775616 + * Defaults to: undefined * @type number * @memberof PersonsApigetV2PersonsIdListEntries */ id: number /** * Cursor for the next or previous page + * Defaults to: undefined * @type string * @memberof PersonsApigetV2PersonsIdListEntries */ cursor?: string /** * Number of items to include in the page + * Minimum: 1 + * Maximum: 100 + * Defaults to: 100 * @type number * @memberof PersonsApigetV2PersonsIdListEntries */ @@ -774,18 +882,25 @@ export interface PersonsApiGetV2PersonsIdListEntriesRequest { export interface PersonsApiGetV2PersonsIdListsRequest { /** * Persons ID + * Minimum: 1 + * Maximum: -9223372036854775616 + * Defaults to: undefined * @type number * @memberof PersonsApigetV2PersonsIdLists */ id: number /** * Cursor for the next or previous page + * Defaults to: undefined * @type string * @memberof PersonsApigetV2PersonsIdLists */ cursor?: string /** * Number of items to include in the page + * Minimum: 1 + * Maximum: 100 + * Defaults to: 100 * @type number * @memberof PersonsApigetV2PersonsIdLists */ diff --git a/src/v2/generated/types/ObservableAPI.ts b/src/v2/generated/types/ObservableAPI.ts index 0d300f1..af22821 100644 --- a/src/v2/generated/types/ObservableAPI.ts +++ b/src/v2/generated/types/ObservableAPI.ts @@ -71,6 +71,7 @@ import { Tenant } from '../models/Tenant.ts'; import { TextValue } from '../models/TextValue.ts'; import { TextsValue } from '../models/TextsValue.ts'; import { UnprocessableEntityError } from '../models/UnprocessableEntityError.ts'; +import { UnsupportedMediaTypeError } from '../models/UnsupportedMediaTypeError.ts'; import { User } from '../models/User.ts'; import { ValidationError } from '../models/ValidationError.ts'; import { ValidationErrors } from '../models/ValidationErrors.ts'; @@ -144,11 +145,11 @@ export class ObservableCompaniesApi { /** * 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 + * @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 getV2CompaniesWithHttpInfo(cursor?: string, limit?: number, ids?: Array, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: Configuration): Observable> { const requestContextPromise = this.requestFactory.getV2Companies(cursor, limit, ids, fieldIds, fieldTypes, _options); @@ -172,11 +173,11 @@ export class ObservableCompaniesApi { /** * 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 + * @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 getV2Companies(cursor?: string, limit?: number, ids?: Array, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: Configuration): Observable { return this.getV2CompaniesWithHttpInfo(cursor, limit, ids, fieldIds, fieldTypes, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); @@ -185,8 +186,8 @@ export class ObservableCompaniesApi { /** * 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 + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page */ public getV2CompaniesFieldsWithHttpInfo(cursor?: string, limit?: number, _options?: Configuration): Observable> { const requestContextPromise = this.requestFactory.getV2CompaniesFields(cursor, limit, _options); @@ -210,8 +211,8 @@ export class ObservableCompaniesApi { /** * 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 + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page */ public getV2CompaniesFields(cursor?: string, limit?: number, _options?: Configuration): Observable { return this.getV2CompaniesFieldsWithHttpInfo(cursor, limit, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); @@ -221,8 +222,8 @@ export class ObservableCompaniesApi { * 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 + * @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?: Configuration): Observable> { const requestContextPromise = this.requestFactory.getV2CompaniesId(id, fieldIds, fieldTypes, _options); @@ -247,8 +248,8 @@ export class ObservableCompaniesApi { * 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 + * @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?: Configuration): Observable { return this.getV2CompaniesIdWithHttpInfo(id, fieldIds, fieldTypes, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); @@ -258,8 +259,8 @@ export class ObservableCompaniesApi { * 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 cursor Cursor for the next or previous page - * @param limit Number of items to include in the page + * @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?: Configuration): Observable> { const requestContextPromise = this.requestFactory.getV2CompaniesIdListEntries(id, cursor, limit, _options); @@ -284,8 +285,8 @@ export class ObservableCompaniesApi { * 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 cursor Cursor for the next or previous page - * @param limit Number of items to include in the page + * @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?: Configuration): Observable { return this.getV2CompaniesIdListEntriesWithHttpInfo(id, cursor, limit, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); @@ -295,8 +296,8 @@ export class ObservableCompaniesApi { * Returns metadata for all the Lists on which the given Company appears. * Get a Company\'s Lists * @param id Company ID - * @param cursor Cursor for the next or previous page - * @param limit Number of items to include in the page + * @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?: Configuration): Observable> { const requestContextPromise = this.requestFactory.getV2CompaniesIdLists(id, cursor, limit, _options); @@ -321,8 +322,8 @@ export class ObservableCompaniesApi { * Returns metadata for all the Lists on which the given Company appears. * Get a Company\'s Lists * @param id Company ID - * @param cursor Cursor for the next or previous page - * @param limit Number of items to include in the page + * @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?: Configuration): Observable { return this.getV2CompaniesIdListsWithHttpInfo(id, cursor, limit, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); @@ -349,8 +350,8 @@ export class ObservableListsApi { /** * Returns metadata on Lists. * Get metadata on all Lists - * @param cursor Cursor for the next or previous page - * @param limit Number of items to include in the page + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page */ public getV2ListsWithHttpInfo(cursor?: string, limit?: number, _options?: Configuration): Observable> { const requestContextPromise = this.requestFactory.getV2Lists(cursor, limit, _options); @@ -374,8 +375,8 @@ export class ObservableListsApi { /** * Returns metadata on Lists. * Get metadata on all Lists - * @param cursor Cursor for the next or previous page - * @param limit Number of items to include in the page + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page */ public getV2Lists(cursor?: string, limit?: number, _options?: Configuration): Observable { return this.getV2ListsWithHttpInfo(cursor, limit, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); @@ -418,8 +419,8 @@ export class ObservableListsApi { * 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 + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page */ public getV2ListsListidFieldsWithHttpInfo(listId: number, cursor?: string, limit?: number, _options?: Configuration): Observable> { const requestContextPromise = this.requestFactory.getV2ListsListidFields(listId, cursor, limit, _options); @@ -444,8 +445,8 @@ export class ObservableListsApi { * 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 + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page */ public getV2ListsListidFields(listId: number, cursor?: string, limit?: number, _options?: Configuration): Observable { return this.getV2ListsListidFieldsWithHttpInfo(listId, cursor, limit, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); @@ -455,10 +456,10 @@ export class ObservableListsApi { * 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 + * @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 getV2ListsListidListEntriesWithHttpInfo(listId: number, cursor?: string, limit?: number, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'list' | 'relationship-intelligence'>, _options?: Configuration): Observable> { const requestContextPromise = this.requestFactory.getV2ListsListidListEntries(listId, cursor, limit, fieldIds, fieldTypes, _options); @@ -483,10 +484,10 @@ export class ObservableListsApi { * 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 + * @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 getV2ListsListidListEntries(listId: number, cursor?: string, limit?: number, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'list' | 'relationship-intelligence'>, _options?: Configuration): Observable { return this.getV2ListsListidListEntriesWithHttpInfo(listId, cursor, limit, fieldIds, fieldTypes, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); @@ -496,8 +497,8 @@ export class ObservableListsApi { * 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 + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page */ public getV2ListsListidSavedViewsWithHttpInfo(listId: number, cursor?: string, limit?: number, _options?: Configuration): Observable> { const requestContextPromise = this.requestFactory.getV2ListsListidSavedViews(listId, cursor, limit, _options); @@ -522,8 +523,8 @@ export class ObservableListsApi { * 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 + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page */ public getV2ListsListidSavedViews(listId: number, cursor?: string, limit?: number, _options?: Configuration): Observable { return this.getV2ListsListidSavedViewsWithHttpInfo(listId, cursor, limit, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); @@ -569,8 +570,8 @@ export class ObservableListsApi { * 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 + * @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?: Configuration): Observable> { const requestContextPromise = this.requestFactory.getV2ListsListidSavedViewsViewidListEntries(listId, viewId, cursor, limit, _options); @@ -596,8 +597,8 @@ export class ObservableListsApi { * 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 + * @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?: Configuration): Observable { return this.getV2ListsListidSavedViewsViewidListEntriesWithHttpInfo(listId, viewId, cursor, limit, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); @@ -624,9 +625,9 @@ export class ObservableOpportunitiesApi { /** * 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 ids Opportunity IDs + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + * @param [ids] Opportunity IDs */ public getV2OpportunitiesWithHttpInfo(cursor?: string, limit?: number, ids?: Array, _options?: Configuration): Observable> { const requestContextPromise = this.requestFactory.getV2Opportunities(cursor, limit, ids, _options); @@ -650,9 +651,9 @@ export class ObservableOpportunitiesApi { /** * 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 ids Opportunity IDs + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + * @param [ids] Opportunity IDs */ public getV2Opportunities(cursor?: string, limit?: number, ids?: Array, _options?: Configuration): Observable { return this.getV2OpportunitiesWithHttpInfo(cursor, limit, ids, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); @@ -712,11 +713,11 @@ 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 - * @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 + * @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?: Configuration): Observable> { const requestContextPromise = this.requestFactory.getV2Persons(cursor, limit, ids, fieldIds, fieldTypes, _options); @@ -740,11 +741,11 @@ 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 - * @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 + * @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?: Configuration): Observable { return this.getV2PersonsWithHttpInfo(cursor, limit, ids, fieldIds, fieldTypes, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); @@ -753,8 +754,8 @@ export class ObservablePersonsApi { /** * 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 [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page */ public getV2PersonsFieldsWithHttpInfo(cursor?: string, limit?: number, _options?: Configuration): Observable> { const requestContextPromise = this.requestFactory.getV2PersonsFields(cursor, limit, _options); @@ -778,8 +779,8 @@ export class ObservablePersonsApi { /** * 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 [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page */ public getV2PersonsFields(cursor?: string, limit?: number, _options?: Configuration): Observable { return this.getV2PersonsFieldsWithHttpInfo(cursor, limit, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); @@ -789,8 +790,8 @@ export class ObservablePersonsApi { * 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 + * @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?: Configuration): Observable> { const requestContextPromise = this.requestFactory.getV2PersonsId(id, fieldIds, fieldTypes, _options); @@ -815,8 +816,8 @@ export class ObservablePersonsApi { * 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 + * @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?: Configuration): Observable { return this.getV2PersonsIdWithHttpInfo(id, fieldIds, fieldTypes, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); @@ -826,8 +827,8 @@ export class ObservablePersonsApi { * 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 cursor Cursor for the next or previous page - * @param limit Number of items to include in the page + * @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?: Configuration): Observable> { const requestContextPromise = this.requestFactory.getV2PersonsIdListEntries(id, cursor, limit, _options); @@ -852,8 +853,8 @@ export class ObservablePersonsApi { * 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 cursor Cursor for the next or previous page - * @param limit Number of items to include in the page + * @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?: Configuration): Observable { return this.getV2PersonsIdListEntriesWithHttpInfo(id, cursor, limit, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); @@ -863,8 +864,8 @@ export class ObservablePersonsApi { * Returns metadata for all the Lists on which the given Person appears. * Get a Person\'s Lists * @param id Persons ID - * @param cursor Cursor for the next or previous page - * @param limit Number of items to include in the page + * @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?: Configuration): Observable> { const requestContextPromise = this.requestFactory.getV2PersonsIdLists(id, cursor, limit, _options); @@ -889,8 +890,8 @@ export class ObservablePersonsApi { * Returns metadata for all the Lists on which the given Person appears. * Get a Person\'s Lists * @param id Persons ID - * @param cursor Cursor for the next or previous page - * @param limit Number of items to include in the page + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page */ public getV2PersonsIdLists(id: number, cursor?: string, limit?: number, _options?: Configuration): Observable { return this.getV2PersonsIdListsWithHttpInfo(id, cursor, limit, _options).pipe(map((apiResponse: HttpInfo) => apiResponse.data)); diff --git a/src/v2/generated/types/PromiseAPI.ts b/src/v2/generated/types/PromiseAPI.ts index 9e26091..45db2b9 100644 --- a/src/v2/generated/types/PromiseAPI.ts +++ b/src/v2/generated/types/PromiseAPI.ts @@ -70,6 +70,7 @@ import { Tenant } from '../models/Tenant.ts'; import { TextValue } from '../models/TextValue.ts'; import { TextsValue } from '../models/TextsValue.ts'; import { UnprocessableEntityError } from '../models/UnprocessableEntityError.ts'; +import { UnsupportedMediaTypeError } from '../models/UnsupportedMediaTypeError.ts'; import { User } from '../models/User.ts'; import { ValidationError } from '../models/ValidationError.ts'; import { ValidationErrors } from '../models/ValidationErrors.ts'; @@ -128,11 +129,11 @@ export class PromiseCompaniesApi { /** * 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 + * @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 getV2CompaniesWithHttpInfo(cursor?: string, limit?: number, ids?: Array, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: Configuration): Promise> { const result = this.api.getV2CompaniesWithHttpInfo(cursor, limit, ids, fieldIds, fieldTypes, _options); @@ -142,11 +143,11 @@ export class PromiseCompaniesApi { /** * 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 + * @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 getV2Companies(cursor?: string, limit?: number, ids?: Array, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'relationship-intelligence'>, _options?: Configuration): Promise { const result = this.api.getV2Companies(cursor, limit, ids, fieldIds, fieldTypes, _options); @@ -156,8 +157,8 @@ export class PromiseCompaniesApi { /** * 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 + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page */ public getV2CompaniesFieldsWithHttpInfo(cursor?: string, limit?: number, _options?: Configuration): Promise> { const result = this.api.getV2CompaniesFieldsWithHttpInfo(cursor, limit, _options); @@ -167,8 +168,8 @@ export class PromiseCompaniesApi { /** * 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 + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page */ public getV2CompaniesFields(cursor?: string, limit?: number, _options?: Configuration): Promise { const result = this.api.getV2CompaniesFields(cursor, limit, _options); @@ -179,8 +180,8 @@ export class PromiseCompaniesApi { * 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 + * @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?: Configuration): Promise> { const result = this.api.getV2CompaniesIdWithHttpInfo(id, fieldIds, fieldTypes, _options); @@ -191,8 +192,8 @@ export class PromiseCompaniesApi { * 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 + * @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?: Configuration): Promise { const result = this.api.getV2CompaniesId(id, fieldIds, fieldTypes, _options); @@ -203,8 +204,8 @@ export class PromiseCompaniesApi { * 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 cursor Cursor for the next or previous page - * @param limit Number of items to include in the page + * @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?: Configuration): Promise> { const result = this.api.getV2CompaniesIdListEntriesWithHttpInfo(id, cursor, limit, _options); @@ -215,8 +216,8 @@ export class PromiseCompaniesApi { * 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 cursor Cursor for the next or previous page - * @param limit Number of items to include in the page + * @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?: Configuration): Promise { const result = this.api.getV2CompaniesIdListEntries(id, cursor, limit, _options); @@ -227,8 +228,8 @@ export class PromiseCompaniesApi { * Returns metadata for all the Lists on which the given Company appears. * Get a Company\'s Lists * @param id Company ID - * @param cursor Cursor for the next or previous page - * @param limit Number of items to include in the page + * @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?: Configuration): Promise> { const result = this.api.getV2CompaniesIdListsWithHttpInfo(id, cursor, limit, _options); @@ -239,8 +240,8 @@ export class PromiseCompaniesApi { * Returns metadata for all the Lists on which the given Company appears. * Get a Company\'s Lists * @param id Company ID - * @param cursor Cursor for the next or previous page - * @param limit Number of items to include in the page + * @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?: Configuration): Promise { const result = this.api.getV2CompaniesIdLists(id, cursor, limit, _options); @@ -269,8 +270,8 @@ export class PromiseListsApi { /** * Returns metadata on Lists. * Get metadata on all Lists - * @param cursor Cursor for the next or previous page - * @param limit Number of items to include in the page + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page */ public getV2ListsWithHttpInfo(cursor?: string, limit?: number, _options?: Configuration): Promise> { const result = this.api.getV2ListsWithHttpInfo(cursor, limit, _options); @@ -280,8 +281,8 @@ export class PromiseListsApi { /** * Returns metadata on Lists. * Get metadata on all Lists - * @param cursor Cursor for the next or previous page - * @param limit Number of items to include in the page + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page */ public getV2Lists(cursor?: string, limit?: number, _options?: Configuration): Promise { const result = this.api.getV2Lists(cursor, limit, _options); @@ -312,8 +313,8 @@ export class PromiseListsApi { * 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 + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page */ public getV2ListsListidFieldsWithHttpInfo(listId: number, cursor?: string, limit?: number, _options?: Configuration): Promise> { const result = this.api.getV2ListsListidFieldsWithHttpInfo(listId, cursor, limit, _options); @@ -324,8 +325,8 @@ export class PromiseListsApi { * 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 + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page */ public getV2ListsListidFields(listId: number, cursor?: string, limit?: number, _options?: Configuration): Promise { const result = this.api.getV2ListsListidFields(listId, cursor, limit, _options); @@ -336,10 +337,10 @@ export class PromiseListsApi { * 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 + * @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 getV2ListsListidListEntriesWithHttpInfo(listId: number, cursor?: string, limit?: number, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'list' | 'relationship-intelligence'>, _options?: Configuration): Promise> { const result = this.api.getV2ListsListidListEntriesWithHttpInfo(listId, cursor, limit, fieldIds, fieldTypes, _options); @@ -350,10 +351,10 @@ export class PromiseListsApi { * 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 + * @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 getV2ListsListidListEntries(listId: number, cursor?: string, limit?: number, fieldIds?: Array, fieldTypes?: Array<'enriched' | 'global' | 'list' | 'relationship-intelligence'>, _options?: Configuration): Promise { const result = this.api.getV2ListsListidListEntries(listId, cursor, limit, fieldIds, fieldTypes, _options); @@ -364,8 +365,8 @@ export class PromiseListsApi { * 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 + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page */ public getV2ListsListidSavedViewsWithHttpInfo(listId: number, cursor?: string, limit?: number, _options?: Configuration): Promise> { const result = this.api.getV2ListsListidSavedViewsWithHttpInfo(listId, cursor, limit, _options); @@ -376,8 +377,8 @@ export class PromiseListsApi { * 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 + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page */ public getV2ListsListidSavedViews(listId: number, cursor?: string, limit?: number, _options?: Configuration): Promise { const result = this.api.getV2ListsListidSavedViews(listId, cursor, limit, _options); @@ -411,8 +412,8 @@ export class PromiseListsApi { * 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 + * @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?: Configuration): Promise> { const result = this.api.getV2ListsListidSavedViewsViewidListEntriesWithHttpInfo(listId, viewId, cursor, limit, _options); @@ -424,8 +425,8 @@ export class PromiseListsApi { * 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 + * @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?: Configuration): Promise { const result = this.api.getV2ListsListidSavedViewsViewidListEntries(listId, viewId, cursor, limit, _options); @@ -454,9 +455,9 @@ export class PromiseOpportunitiesApi { /** * 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 ids Opportunity IDs + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + * @param [ids] Opportunity IDs */ public getV2OpportunitiesWithHttpInfo(cursor?: string, limit?: number, ids?: Array, _options?: Configuration): Promise> { const result = this.api.getV2OpportunitiesWithHttpInfo(cursor, limit, ids, _options); @@ -466,9 +467,9 @@ export class PromiseOpportunitiesApi { /** * 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 ids Opportunity IDs + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page + * @param [ids] Opportunity IDs */ public getV2Opportunities(cursor?: string, limit?: number, ids?: Array, _options?: Configuration): Promise { const result = this.api.getV2Opportunities(cursor, limit, ids, _options); @@ -517,11 +518,11 @@ 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 - * @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 + * @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?: Configuration): Promise> { const result = this.api.getV2PersonsWithHttpInfo(cursor, limit, ids, fieldIds, fieldTypes, _options); @@ -531,11 +532,11 @@ 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 - * @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 + * @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?: Configuration): Promise { const result = this.api.getV2Persons(cursor, limit, ids, fieldIds, fieldTypes, _options); @@ -545,8 +546,8 @@ export class PromisePersonsApi { /** * 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 [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page */ public getV2PersonsFieldsWithHttpInfo(cursor?: string, limit?: number, _options?: Configuration): Promise> { const result = this.api.getV2PersonsFieldsWithHttpInfo(cursor, limit, _options); @@ -556,8 +557,8 @@ export class PromisePersonsApi { /** * 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 [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page */ public getV2PersonsFields(cursor?: string, limit?: number, _options?: Configuration): Promise { const result = this.api.getV2PersonsFields(cursor, limit, _options); @@ -568,8 +569,8 @@ export class PromisePersonsApi { * 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 + * @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?: Configuration): Promise> { const result = this.api.getV2PersonsIdWithHttpInfo(id, fieldIds, fieldTypes, _options); @@ -580,8 +581,8 @@ export class PromisePersonsApi { * 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 + * @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?: Configuration): Promise { const result = this.api.getV2PersonsId(id, fieldIds, fieldTypes, _options); @@ -592,8 +593,8 @@ export class PromisePersonsApi { * 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 cursor Cursor for the next or previous page - * @param limit Number of items to include in the page + * @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?: Configuration): Promise> { const result = this.api.getV2PersonsIdListEntriesWithHttpInfo(id, cursor, limit, _options); @@ -604,8 +605,8 @@ export class PromisePersonsApi { * 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 cursor Cursor for the next or previous page - * @param limit Number of items to include in the page + * @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?: Configuration): Promise { const result = this.api.getV2PersonsIdListEntries(id, cursor, limit, _options); @@ -616,8 +617,8 @@ export class PromisePersonsApi { * Returns metadata for all the Lists on which the given Person appears. * Get a Person\'s Lists * @param id Persons ID - * @param cursor Cursor for the next or previous page - * @param limit Number of items to include in the page + * @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?: Configuration): Promise> { const result = this.api.getV2PersonsIdListsWithHttpInfo(id, cursor, limit, _options); @@ -628,8 +629,8 @@ export class PromisePersonsApi { * Returns metadata for all the Lists on which the given Person appears. * Get a Person\'s Lists * @param id Persons ID - * @param cursor Cursor for the next or previous page - * @param limit Number of items to include in the page + * @param [cursor] Cursor for the next or previous page + * @param [limit] Number of items to include in the page */ public getV2PersonsIdLists(id: number, cursor?: string, limit?: number, _options?: Configuration): Promise { const result = this.api.getV2PersonsIdLists(id, cursor, limit, _options); From 1244b6593cc5f30a3962d9cf801d2d54c360fb44 Mon Sep 17 00:00:00 2001 From: Joscha Feth Date: Tue, 8 Oct 2024 11:38:40 +0100 Subject: [PATCH 7/9] chore: update lock file --- deno.jsonc | 2 +- deno.lock | 249 ++++++++++++++--------------------------------------- 2 files changed, 67 insertions(+), 184 deletions(-) diff --git a/deno.jsonc b/deno.jsonc index 6a3c0e6..50bcb10 100644 --- a/deno.jsonc +++ b/deno.jsonc @@ -28,7 +28,7 @@ "generate-v2-client": "rm -rf src/v2/generated && deno run --allow-read --allow-run --allow-env --allow-write=openapitools.json,node_modules,/tmp,/var --allow-net='search.maven.org,repo1.maven.org,oss.sonatype.org:443' npm:@openapitools/openapi-generator-cli@2.14.0 generate", "update-deno-lock": "deno cache --lock-write src/index.ts", "update-flake-lock": "nix --option commit-lockfile-summary 'chore: update flake.lock' flake update --commit-lock-file", - "update": "deno run --allow-env --allow-read --allow-write='~/.local,.' --allow-run=git,deno --allow-net=jsr.io jsr:@molt/cli", + "update": "deno run --allow-env --allow-read --allow-write='~/.local,.' --allow-run=git,deno --allow-net='api.jsr.io,jsr.io,registry.npmjs.org' jsr:@molt/cli", "update:commit": "deno task -q update --commit" }, "lint": { diff --git a/deno.lock b/deno.lock index 65d2d00..5a4ad54 100644 --- a/deno.lock +++ b/deno.lock @@ -7,46 +7,45 @@ "jsr:@deno/dnt@^0.41.3": "jsr:@deno/dnt@0.41.3", "jsr:@std/assert@^0.223.0": "jsr:@std/assert@0.223.0", "jsr:@std/assert@^0.226.0": "jsr:@std/assert@0.226.0", - "jsr:@std/assert@^1.0.0": "jsr:@std/assert@1.0.2", - "jsr:@std/assert@^1.0.2": "jsr:@std/assert@1.0.2", - "jsr:@std/async@^1.0.2": "jsr:@std/async@1.0.3", + "jsr:@std/assert@^1.0.0": "jsr:@std/assert@1.0.6", + "jsr:@std/assert@^1.0.6": "jsr:@std/assert@1.0.6", + "jsr:@std/async@^1.0.5": "jsr:@std/async@1.0.5", "jsr:@std/bytes@^0.223.0": "jsr:@std/bytes@0.223.0", - "jsr:@std/bytes@^1.0.2-rc.3": "jsr:@std/bytes@1.0.2", - "jsr:@std/data-structures@^1.0.1": "jsr:@std/data-structures@1.0.1", + "jsr:@std/bytes@^1.0.2": "jsr:@std/bytes@1.0.2", + "jsr:@std/data-structures@^1.0.4": "jsr:@std/data-structures@1.0.4", "jsr:@std/fmt@1": "jsr:@std/fmt@1.0.2", "jsr:@std/fmt@^0.223": "jsr:@std/fmt@0.223.0", "jsr:@std/fmt@^0.225.3": "jsr:@std/fmt@0.225.3", "jsr:@std/fs@1": "jsr:@std/fs@1.0.1", "jsr:@std/fs@^0.223": "jsr:@std/fs@0.223.0", "jsr:@std/fs@^0.229.3": "jsr:@std/fs@0.229.3", - "jsr:@std/fs@^1.0.0": "jsr:@std/fs@1.0.1", + "jsr:@std/fs@^1.0.0": "jsr:@std/fs@1.0.4", "jsr:@std/fs@^1.0.1": "jsr:@std/fs@1.0.1", - "jsr:@std/internal@^1.0.0": "jsr:@std/internal@1.0.1", - "jsr:@std/internal@^1.0.1": "jsr:@std/internal@1.0.1", + "jsr:@std/fs@^1.0.4": "jsr:@std/fs@1.0.4", + "jsr:@std/internal@^1.0.4": "jsr:@std/internal@1.0.4", "jsr:@std/io": "jsr:@std/io@0.223.0", "jsr:@std/io@^0.223": "jsr:@std/io@0.223.0", - "jsr:@std/jsonc@^1.0.0": "jsr:@std/jsonc@1.0.0", + "jsr:@std/json@^1.0.0": "jsr:@std/json@1.0.0", + "jsr:@std/jsonc@^1.0.0": "jsr:@std/jsonc@1.0.1", "jsr:@std/path@1": "jsr:@std/path@1.0.2", "jsr:@std/path@1.0.0-rc.1": "jsr:@std/path@1.0.0-rc.1", "jsr:@std/path@^0.223": "jsr:@std/path@0.223.0", "jsr:@std/path@^0.225.2": "jsr:@std/path@0.225.2", - "jsr:@std/path@^1.0.0": "jsr:@std/path@1.0.2", + "jsr:@std/path@^1.0.0": "jsr:@std/path@1.0.6", "jsr:@std/path@^1.0.2": "jsr:@std/path@1.0.2", - "jsr:@std/streams@^1.0.0": "jsr:@std/streams@1.0.1", - "jsr:@std/testing@^1.0.0": "jsr:@std/testing@1.0.0", + "jsr:@std/path@^1.0.6": "jsr:@std/path@1.0.6", + "jsr:@std/streams@^1.0.0": "jsr:@std/streams@1.0.6", + "jsr:@std/testing@^1.0.0": "jsr:@std/testing@1.0.3", "jsr:@ts-morph/bootstrap@^0.24.0": "jsr:@ts-morph/bootstrap@0.24.0", "jsr:@ts-morph/common@^0.24.0": "jsr:@ts-morph/common@0.24.0", "npm:@openapitools/openapi-generator-cli@2.13.4": "npm:@openapitools/openapi-generator-cli@2.13.4_@nestjs+common@10.3.0__reflect-metadata@0.1.13__rxjs@7.8.1_axios@1.6.8_rxjs@7.8.1_reflect-metadata@0.1.13", - "npm:@openapitools/openapi-generator-cli@2.13.5": "npm:@openapitools/openapi-generator-cli@2.13.5_@nestjs+common@10.3.0__reflect-metadata@0.1.13__rxjs@7.8.1_axios@1.7.4_rxjs@7.8.1_reflect-metadata@0.1.13", "npm:@openapitools/openapi-generator-cli@2.14.0": "npm:@openapitools/openapi-generator-cli@2.14.0_@nestjs+common@10.4.3__reflect-metadata@0.1.13__rxjs@7.8.1_axios@1.7.7_rxjs@7.8.1_reflect-metadata@0.1.13", "npm:@types/node": "npm:@types/node@18.16.19", - "npm:axios-mock-adapter@^2.0.0": "npm:axios-mock-adapter@2.0.0_axios@1.7.4", - "npm:axios@^1.7.3": "npm:axios@1.7.4", + "npm:axios@^1.7.3": "npm:axios@1.7.7", "npm:fetch-blob@^4.0.0": "npm:fetch-blob@4.0.0", - "npm:fetch-mock@^11.1.3": "npm:fetch-mock@11.1.3", + "npm:fetch-mock@^11.1.3": "npm:fetch-mock@11.1.5", "npm:typedoc@0.25.13": "npm:typedoc@0.25.13_typescript@5.4.5", - "npm:typedoc@0.26.6": "npm:typedoc@0.26.6_typescript@5.5.4", - "npm:typescript@^5.4.5": "npm:typescript@5.5.4" + "npm:typescript@^5.4.5": "npm:typescript@5.6.2" }, "jsr": { "@david/code-block-writer@13.0.2": { @@ -78,14 +77,14 @@ "@std/assert@0.226.0": { "integrity": "0dfb5f7c7723c18cec118e080fec76ce15b4c31154b15ad2bd74822603ef75b3" }, - "@std/assert@1.0.2": { - "integrity": "ccacec332958126deaceb5c63ff8b4eaf9f5ed0eac9feccf124110435e59e49c", + "@std/assert@1.0.6": { + "integrity": "1904c05806a25d94fe791d6d883b685c9e2dcd60e4f9fc30f4fc5cf010c72207", "dependencies": [ - "jsr:@std/internal@^1.0.1" + "jsr:@std/internal@^1.0.4" ] }, - "@std/async@1.0.3": { - "integrity": "6ed64678db43451683c6c176a21426a2ccd21ba0269ebb2c36133ede3f165792" + "@std/async@1.0.5": { + "integrity": "31d68214bfbb31bd4c6022401d484e3964147c76c9220098baa703a39b6c2da6" }, "@std/bytes@0.223.0": { "integrity": "84b75052cd8680942c397c2631318772b295019098f40aac5c36cead4cba51a8" @@ -93,8 +92,8 @@ "@std/bytes@1.0.2": { "integrity": "fbdee322bbd8c599a6af186a1603b3355e59a5fb1baa139f8f4c3c9a1b3e3d57" }, - "@std/data-structures@1.0.1": { - "integrity": "e4fa6bcc33839979ac118e2746f349cd7b57c58bd3036b5b82ac608771ee856e" + "@std/data-structures@1.0.4": { + "integrity": "fa0e20c11eb9ba673417450915c750a0001405a784e2a4e0c3725031681684a0" }, "@std/fmt@0.223.0": { "integrity": "6deb37794127dfc7d7bded2586b9fc6f5d50e62a8134846608baf71ffc1a5208" @@ -120,11 +119,17 @@ "jsr:@std/path@^1.0.2" ] }, + "@std/fs@1.0.4": { + "integrity": "2907d32d8d1d9e540588fd5fe0ec21ee638134bd51df327ad4e443aaef07123c", + "dependencies": [ + "jsr:@std/path@^1.0.6" + ] + }, "@std/internal@1.0.0": { "integrity": "ac6a6dfebf838582c4b4f61a6907374e27e05bedb6ce276e0f1608fe84e7cd9a" }, - "@std/internal@1.0.1": { - "integrity": "6f8c7544d06a11dd256c8d6ba54b11ed870aac6c5aeafff499892662c57673e6" + "@std/internal@1.0.4": { + "integrity": "62e8e4911527e5e4f307741a795c0b0a9e6958d0b3790716ae71ce085f755422" }, "@std/io@0.223.0": { "integrity": "2d8c3c2ab3a515619b90da2c6ff5ea7b75a94383259ef4d02116b228393f84f1", @@ -133,8 +138,17 @@ "jsr:@std/bytes@^0.223.0" ] }, - "@std/jsonc@1.0.0": { - "integrity": "835da212e586f3ef94ab25e8f0e8a7711a86fddbee95ad40c34d6b3d74da1a1b" + "@std/json@1.0.0": { + "integrity": "985c1e544918d42e4e84072fc739ac4a19c3a5093292c99742ffcdd03fb6a268", + "dependencies": [ + "jsr:@std/streams@^1.0.0" + ] + }, + "@std/jsonc@1.0.1": { + "integrity": "6b36956e2a7cbb08ca5ad7fbec72e661e6217c202f348496ea88747636710dda", + "dependencies": [ + "jsr:@std/json@^1.0.0" + ] }, "@std/path@0.223.0": { "integrity": "593963402d7e6597f5a6e620931661053572c982fc014000459edc1f93cc3989", @@ -154,10 +168,13 @@ "@std/path@1.0.2": { "integrity": "a452174603f8c620bd278a380c596437a9eef50c891c64b85812f735245d9ec7" }, - "@std/streams@1.0.1": { - "integrity": "b07008b83fd7ae08965920d0fd700e07caf233bdd81e0ef1c8cca6c4140da364", + "@std/path@1.0.6": { + "integrity": "ab2c55f902b380cf28e0eec501b4906e4c1960d13f00e11cfbcd21de15f18fed" + }, + "@std/streams@1.0.6": { + "integrity": "022ed94e380d06b4d91c49eb70241b7289ab78b8c2b4c4bbb7eb265e4997c25c", "dependencies": [ - "jsr:@std/bytes@^1.0.2-rc.3" + "jsr:@std/bytes@^1.0.2" ] }, "@std/testing@0.225.0": { @@ -170,15 +187,15 @@ "jsr:@std/path@^0.225.2" ] }, - "@std/testing@1.0.0": { - "integrity": "27cfc06392c69c2acffe54e6d0bcb5f961cf193f519255372bd4fff1481bfef8", + "@std/testing@1.0.3": { + "integrity": "f98c2bee53860a5916727d7e7d3abe920dd6f9edace022e2d059f00d05c2cf42", "dependencies": [ - "jsr:@std/assert@^1.0.2", - "jsr:@std/async@^1.0.2", - "jsr:@std/data-structures@^1.0.1", - "jsr:@std/fs@^1.0.1", - "jsr:@std/internal@^1.0.1", - "jsr:@std/path@^1.0.2" + "jsr:@std/assert@^1.0.6", + "jsr:@std/async@^1.0.5", + "jsr:@std/data-structures@^1.0.4", + "jsr:@std/fs@^1.0.4", + "jsr:@std/internal@^1.0.4", + "jsr:@std/path@^1.0.6" ] }, "@ts-morph/bootstrap@0.24.0": { @@ -214,14 +231,6 @@ "rxjs": "rxjs@7.8.1" } }, - "@nestjs/axios@3.0.2_@nestjs+common@10.3.0__reflect-metadata@0.1.13__rxjs@7.8.1_axios@1.7.4_rxjs@7.8.1_reflect-metadata@0.1.13": { - "integrity": "sha512-Z6GuOUdNQjP7FX+OuV2Ybyamse+/e0BFdTWBX5JxpBDKA+YkdLynDgG6HTF04zy6e9zPa19UX0WA2VDoehwhXQ==", - "dependencies": { - "@nestjs/common": "@nestjs/common@10.3.0_reflect-metadata@0.1.13_rxjs@7.8.1", - "axios": "axios@1.7.4", - "rxjs": "rxjs@7.8.1" - } - }, "@nestjs/axios@3.0.3_@nestjs+common@10.4.3__reflect-metadata@0.1.13__rxjs@7.8.1_axios@1.7.7_rxjs@7.8.1_reflect-metadata@0.1.13": { "integrity": "sha512-h6TCn3yJwD6OKqqqfmtRS5Zo4E46Ip2n+gK1sqwzNBC+qxQ9xpCu+ODVRFur6V3alHSCSBxb3nNtt73VEdluyA==", "dependencies": { @@ -309,29 +318,6 @@ "tslib": "tslib@2.6.2" } }, - "@openapitools/openapi-generator-cli@2.13.5_@nestjs+common@10.3.0__reflect-metadata@0.1.13__rxjs@7.8.1_axios@1.7.4_rxjs@7.8.1_reflect-metadata@0.1.13": { - "integrity": "sha512-9VgeKOTiiatKSwZDKKB3C86cW8tN9eDcFohotD4eisdK38UQswk/4Ysoq9KChRCbymjoMp6AIDHPtK1DQ2fTgw==", - "dependencies": { - "@nestjs/axios": "@nestjs/axios@3.0.2_@nestjs+common@10.3.0__reflect-metadata@0.1.13__rxjs@7.8.1_axios@1.7.4_rxjs@7.8.1_reflect-metadata@0.1.13", - "@nestjs/common": "@nestjs/common@10.3.0_reflect-metadata@0.1.13_rxjs@7.8.1", - "@nestjs/core": "@nestjs/core@10.3.0_@nestjs+common@10.3.0__reflect-metadata@0.1.13__rxjs@7.8.1_reflect-metadata@0.1.13_rxjs@7.8.1", - "@nuxtjs/opencollective": "@nuxtjs/opencollective@0.3.2", - "axios": "axios@1.7.4", - "chalk": "chalk@4.1.2", - "commander": "commander@8.3.0", - "compare-versions": "compare-versions@4.1.4", - "concurrently": "concurrently@6.5.1", - "console.table": "console.table@0.10.0", - "fs-extra": "fs-extra@10.1.0", - "glob": "glob@7.2.3", - "https-proxy-agent": "https-proxy-agent@7.0.4", - "inquirer": "inquirer@8.2.6", - "lodash": "lodash@4.17.21", - "reflect-metadata": "reflect-metadata@0.1.13", - "rxjs": "rxjs@7.8.1", - "tslib": "tslib@2.6.2" - } - }, "@openapitools/openapi-generator-cli@2.14.0_@nestjs+common@10.4.3__reflect-metadata@0.1.13__rxjs@7.8.1_axios@1.7.7_rxjs@7.8.1_reflect-metadata@0.1.13": { "integrity": "sha512-k+ioQLtXLXgNbhQbp1UOxtaUnnYTWwAPev88hP5qauFA+eq4NyeQGNojknFssXg2x0VT0TUGmU3PZ2DiQ70IVg==", "dependencies": { @@ -355,35 +341,14 @@ "tslib": "tslib@2.7.0" } }, - "@shikijs/core@1.16.1": { - "integrity": "sha512-aI0hBtw+a6KsJp2jcD4YuQqKpeCbURMZbhHVozDknJpm+KJqeMRkEnfBC8BaKE/5XC+uofPgCLsa/TkTk0Ba0w==", - "dependencies": { - "@shikijs/vscode-textmate": "@shikijs/vscode-textmate@9.2.0", - "@types/hast": "@types/hast@3.0.4" - } - }, - "@shikijs/vscode-textmate@9.2.0": { - "integrity": "sha512-5FinaOp6Vdh/dl4/yaOTh0ZeKch+rYS8DUb38V3GMKYVkdqzxw53lViRKUYkVILRiVQT7dcPC7VvAKOR73zVtQ==", - "dependencies": {} - }, "@types/glob-to-regexp@0.4.4": { "integrity": "sha512-nDKoaKJYbnn1MZxUY0cA1bPmmgZbg0cTq7Rh13d0KWYNOiKbqoR+2d89SnRPszGh7ROzSwZ/GOjZ4jPbmmZ6Eg==", "dependencies": {} }, - "@types/hast@3.0.4": { - "integrity": "sha512-WPs+bbQw5aCj+x6laNGWLH3wviHtoCv/P3+otBhbOhJgG8qtpdAMlTCxLtsTWA7LH1Oh/bFCHsBn0TPS5m30EQ==", - "dependencies": { - "@types/unist": "@types/unist@3.0.3" - } - }, "@types/node@18.16.19": { "integrity": "sha512-IXl7o+R9iti9eBW4Wg2hx1xQDig183jj7YLn8F7udNceyfkbn1ZxmzZXuak20gR40D7pIkIY1kYGx5VIGbaHKA==", "dependencies": {} }, - "@types/unist@3.0.3": { - "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==", - "dependencies": {} - }, "agent-base@7.1.1": { "integrity": "sha512-H0TSyFNDMomMNJQBn8wFV5YC/2eJ+VXECwOadZJT554xP6cODZHPX3H9QMQECxvrgiSOP1pHjy1sMWQVYJOUOA==", "dependencies": { @@ -410,22 +375,10 @@ "color-convert": "color-convert@2.0.1" } }, - "argparse@2.0.1": { - "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==", - "dependencies": {} - }, "asynckit@0.4.0": { "integrity": "sha512-Oei9OH4tRh0YqU3GxhX79dM/mwVgvbZJaSNaRk+bshkj0S5cfHcgYakreBjrHwatXKbz+IoIdYLxrKim2MjW0Q==", "dependencies": {} }, - "axios-mock-adapter@2.0.0_axios@1.7.4": { - "integrity": "sha512-D/K0J5Zm6KvaMTnsWrBQZWLzKN9GxUFZEa0mx2qeEHXDeTugCoplWehy8y36dj5vuSjhe1u/Dol8cZ8lzzmDew==", - "dependencies": { - "axios": "axios@1.7.4", - "fast-deep-equal": "fast-deep-equal@3.1.3", - "is-buffer": "is-buffer@2.0.5" - } - }, "axios@1.6.8": { "integrity": "sha512-v/ZHtJDU39mDpyBoFVkETcd/uNdxrWRrg3bKpOKzXFA6Bvqopts6ALSMU3y6ijYxbw2B+wPrIv46egTzJXCLGQ==", "dependencies": { @@ -434,14 +387,6 @@ "proxy-from-env": "proxy-from-env@1.1.0" } }, - "axios@1.7.4": { - "integrity": "sha512-DukmaFRnY6AzAALSH4J2M3k6PkaC+MfaAGdEERRWcC9q3/TWQwLpHR8ZRLKTdQ3aBDL64EdluRDjJqKw+BPZEw==", - "dependencies": { - "follow-redirects": "follow-redirects@1.15.6", - "form-data": "form-data@4.0.0", - "proxy-from-env": "proxy-from-env@1.1.0" - } - }, "axios@1.7.7": { "integrity": "sha512-S4kL7XrjgBmvdGut0sN3yJxqYzrDOnivkBiN0OFs6hLiUam3UPvswUo0kqGyhqUZGEOytHyumEdXsAkgCOUf3Q==", "dependencies": { @@ -610,10 +555,6 @@ "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==", "dependencies": {} }, - "entities@4.5.0": { - "integrity": "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==", - "dependencies": {} - }, "escalade@3.1.2": { "integrity": "sha512-ErCHMCae19vR8vQGe50xIsVomy19rg6gFu3+r3jkEO46suLMWBksvVyoGgQV+jOfl84ZSOSlmv6Gxa89PmTGmA==", "dependencies": {} @@ -630,10 +571,6 @@ "tmp": "tmp@0.0.33" } }, - "fast-deep-equal@3.1.3": { - "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==", - "dependencies": {} - }, "fast-safe-stringify@2.1.1": { "integrity": "sha512-W+KJc2dmILlPplD/H4K9l9LcAHAfPtP6BY84uVLXQ6Evcz9Lcg33Y2z1IVblT6xdY54PXYVHEv+0Wpq8Io6zkA==", "dependencies": {} @@ -644,8 +581,8 @@ "node-domexception": "node-domexception@1.0.0" } }, - "fetch-mock@11.1.3": { - "integrity": "sha512-ATh0dWgnVrUHiiXuvQm1Ry+ThWfSv1QQgqJTCtybrNxyUrFiSOaDKsNG29eyysp1SHeNP6Q+dH50+8VifN51Ig==", + "fetch-mock@11.1.5": { + "integrity": "sha512-KHmZDnZ1ry0pCTrX4YG5DtThHi0MH+GNI9caESnzX/nMJBrvppUHMvLx47M0WY9oAtKOMiPfZDRpxhlHg89BOA==", "dependencies": { "@types/glob-to-regexp": "@types/glob-to-regexp@0.4.4", "dequal": "dequal@2.0.3", @@ -664,6 +601,10 @@ "integrity": "sha512-wWN62YITEaOpSK584EZXJafH1AGpO8RVgElfkuXbTOrPX4fIfOyEpW/CsiNd8JdYrAoOvafRTOEnvsO++qCqFA==", "dependencies": {} }, + "follow-redirects@1.15.9": { + "integrity": "sha512-gew4GsXizNgdoRyqmyfMHyAmXsZDk6mHkSxZFCzW9gwlbtOW44CDtYavM+y+72qD/Vq2l550kMF52DT8fOLJqQ==", + "dependencies": {} + }, "form-data@4.0.0": { "integrity": "sha512-ETEklSGi5t0QMZuiXoA/Q6vcnxcLQP5vdugSpuAyi6SVGi2clPPp+xgEhuMaHC+zGgn31Kd235W35f7Hykkaww==", "dependencies": { @@ -775,10 +716,6 @@ "wrap-ansi": "wrap-ansi@6.2.0" } }, - "is-buffer@2.0.5": { - "integrity": "sha512-i2R6zNFDwgEHJyQUtJEk0XFi1i0dPFn/oqjK3/vPCcDeJvW5NQ83V8QbicfF1SupOaB0h8ntgBC2YiE7dfyctQ==", - "dependencies": {} - }, "is-fullwidth-code-point@3.0.0": { "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==", "dependencies": {} @@ -810,12 +747,6 @@ "universalify": "universalify@2.0.1" } }, - "linkify-it@5.0.0": { - "integrity": "sha512-5aHCbzQRADcdP+ATqnDuhhJ/MRIqDkZX5pyjFHRRysS8vZ5AbqGEoFIb6pYHPZ+L/OC2Lc+xT8uHVVR5CAK/wQ==", - "dependencies": { - "uc.micro": "uc.micro@2.1.0" - } - }, "lodash@4.17.21": { "integrity": "sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg==", "dependencies": {} @@ -835,25 +766,10 @@ "integrity": "sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==", "dependencies": {} }, - "markdown-it@14.1.0": { - "integrity": "sha512-a54IwgWPaeBCAAsv13YgmALOF1elABB08FxO9i+r4VFk5Vl4pKokRPeX8u5TCgSsPi6ec1otfLjdOpVcgbpshg==", - "dependencies": { - "argparse": "argparse@2.0.1", - "entities": "entities@4.5.0", - "linkify-it": "linkify-it@5.0.0", - "mdurl": "mdurl@2.0.0", - "punycode.js": "punycode.js@2.3.1", - "uc.micro": "uc.micro@2.1.0" - } - }, "marked@4.3.0": { "integrity": "sha512-PRsaiG84bK+AMvxziE/lCFss8juXjNaWzVbN5tXAm4XjeaS9NAHhop+PjQxz2A9h8Q4M/xGmzP8vqNwy6JeK0A==", "dependencies": {} }, - "mdurl@2.0.0": { - "integrity": "sha512-Lf+9+2r+Tdp5wXDXC4PcIBjTDtq4UKjCPMQhKIuzpJNW0b96kVqSwW0bT7FhRSfmAiFYgP+SCRvdrDozfh0U5w==", - "dependencies": {} - }, "mime-db@1.52.0": { "integrity": "sha512-sPU4uV7dYlvtWJxwwxHD0PuihVNiE7TyAbQ5SWxDCB9mUYvOgroQOwYQQOKPJ8CIbE+1ETVlOoK1UC2nU3gYvg==", "dependencies": {} @@ -965,10 +881,6 @@ "integrity": "sha512-D+zkORCbA9f1tdWRK0RaCR3GPv50cMxcrz4X8k5LTSUD1Dkw47mKJEZQNunItRTkWwgtaUSo1RVFRIG9ZXiFYg==", "dependencies": {} }, - "punycode.js@2.3.1": { - "integrity": "sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA==", - "dependencies": {} - }, "readable-stream@3.6.2": { "integrity": "sha512-9u/sniCrY3D5WdsERHzHE4G2YCXqoG5FTHUiCC4SIbr6XcLZBY05ya9EKjYek9O5xOAwjGq+1JdGBAS7Q9ScoA==", "dependencies": { @@ -1033,14 +945,6 @@ "vscode-textmate": "vscode-textmate@8.0.0" } }, - "shiki@1.16.1": { - "integrity": "sha512-tCJIMaxDVB1mEIJ5TvfZU7kCPB5eo9fli5+21Olc/bmyv+w8kye3JOp+LZRmGkAyT71hrkefQhTiY+o9mBikRQ==", - "dependencies": { - "@shikijs/core": "@shikijs/core@1.16.1", - "@shikijs/vscode-textmate": "@shikijs/vscode-textmate@9.2.0", - "@types/hast": "@types/hast@3.0.4" - } - }, "signal-exit@3.0.7": { "integrity": "sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ==", "dependencies": {} @@ -1125,27 +1029,12 @@ "typescript": "typescript@5.4.5" } }, - "typedoc@0.26.6_typescript@5.5.4": { - "integrity": "sha512-SfEU3SH3wHNaxhFPjaZE2kNl/NFtLNW5c1oHsg7mti7GjmUj1Roq6osBQeMd+F4kL0BoRBBr8gQAuqBlfFu8LA==", - "dependencies": { - "lunr": "lunr@2.3.9", - "markdown-it": "markdown-it@14.1.0", - "minimatch": "minimatch@9.0.5", - "shiki": "shiki@1.16.1", - "typescript": "typescript@5.5.4", - "yaml": "yaml@2.5.1" - } - }, "typescript@5.4.5": { "integrity": "sha512-vcI4UpRgg81oIRUFwR0WSIHKt11nJ7SAVlYNIu+QpqeyXP+gpQJy/Z4+F0aGxSE4MqwjyXvW/TzgkLAx2AGHwQ==", "dependencies": {} }, - "typescript@5.5.4": { - "integrity": "sha512-Mtq29sKDAEYP7aljRgtPOpTvOfbwRWlS6dPRzwjdE+C0R4brX/GUyhHSecbHMFLNBLcJIPt9nl9yG5TZ1weH+Q==", - "dependencies": {} - }, - "uc.micro@2.1.0": { - "integrity": "sha512-ARDJmphmdvUk6Glw7y9DQ2bFkKBHwQHLi2lsaH6PPmz/Ka9sFOBsBluozhDltWmnv9u/cF6Rt87znRTPV+yp/A==", + "typescript@5.6.2": { + "integrity": "sha512-NW8ByodCSNCwZeghjN3o+JX5OFH0Ojg6sadjEKY4huZ52TqbJTJnDo5+Tw98lSy63NZvi4n+ez5m2u5d4PkZyw==", "dependencies": {} }, "uid@2.0.2": { @@ -1211,10 +1100,6 @@ "integrity": "sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==", "dependencies": {} }, - "yaml@2.5.1": { - "integrity": "sha512-bLQOjaX/ADgQ20isPJRvF0iRUHIxVhYvr53Of7wGcWlO2jvtUlH5m87DsmulFVxRpNLOnI4tB6p/oh8D7kpn9Q==", - "dependencies": {} - }, "yargs-parser@20.2.9": { "integrity": "sha512-y11nGElTIV+CT3Zv9t7VKl+Q3hTQoT9a1Qzezhhl6Rp21gJ/IVTW7Z3y9EWXhuUBC2Shnf+DX0antecpAwSP8w==", "dependencies": {} @@ -1233,9 +1118,7 @@ } } }, - "remote": { - "https://deno.land/x/keypress@0.0.11/mod.ts": "22fe0ea62136f3015149c639f891076a5b2312c0b8974c4a2bd8acaaded61c61" - }, + "remote": {}, "workspace": { "dependencies": [ "jsr:@deno/dnt@^0.41.3", From 57057824539206a90b45656d226403bf95a6ee30 Mon Sep 17 00:00:00 2001 From: Joscha Feth Date: Tue, 8 Oct 2024 11:49:07 +0100 Subject: [PATCH 8/9] chore: declutter lock file --- deno.lock | 670 ++++++++++++++++++++++++++---------------------------- 1 file changed, 325 insertions(+), 345 deletions(-) diff --git a/deno.lock b/deno.lock index 5a4ad54..8098f90 100644 --- a/deno.lock +++ b/deno.lock @@ -2,219 +2,66 @@ "version": "3", "packages": { "specifiers": { - "jsr:@david/code-block-writer@^13.0.2": "jsr:@david/code-block-writer@13.0.2", - "jsr:@deno/cache-dir@^0.10.3": "jsr:@deno/cache-dir@0.10.3", - "jsr:@deno/dnt@^0.41.3": "jsr:@deno/dnt@0.41.3", - "jsr:@std/assert@^0.223.0": "jsr:@std/assert@0.223.0", - "jsr:@std/assert@^0.226.0": "jsr:@std/assert@0.226.0", "jsr:@std/assert@^1.0.0": "jsr:@std/assert@1.0.6", - "jsr:@std/assert@^1.0.6": "jsr:@std/assert@1.0.6", - "jsr:@std/async@^1.0.5": "jsr:@std/async@1.0.5", - "jsr:@std/bytes@^0.223.0": "jsr:@std/bytes@0.223.0", + "jsr:@std/assert@^1.0.2": "jsr:@std/assert@1.0.6", "jsr:@std/bytes@^1.0.2": "jsr:@std/bytes@1.0.2", - "jsr:@std/data-structures@^1.0.4": "jsr:@std/data-structures@1.0.4", - "jsr:@std/fmt@1": "jsr:@std/fmt@1.0.2", - "jsr:@std/fmt@^0.223": "jsr:@std/fmt@0.223.0", - "jsr:@std/fmt@^0.225.3": "jsr:@std/fmt@0.225.3", - "jsr:@std/fs@1": "jsr:@std/fs@1.0.1", - "jsr:@std/fs@^0.223": "jsr:@std/fs@0.223.0", - "jsr:@std/fs@^0.229.3": "jsr:@std/fs@0.229.3", - "jsr:@std/fs@^1.0.0": "jsr:@std/fs@1.0.4", - "jsr:@std/fs@^1.0.1": "jsr:@std/fs@1.0.1", - "jsr:@std/fs@^1.0.4": "jsr:@std/fs@1.0.4", + "jsr:@std/fs@^1.0.1": "jsr:@std/fs@1.0.4", + "jsr:@std/internal@^1.0.1": "jsr:@std/internal@1.0.4", "jsr:@std/internal@^1.0.4": "jsr:@std/internal@1.0.4", - "jsr:@std/io": "jsr:@std/io@0.223.0", - "jsr:@std/io@^0.223": "jsr:@std/io@0.223.0", - "jsr:@std/json@^1.0.0": "jsr:@std/json@1.0.0", - "jsr:@std/jsonc@^1.0.0": "jsr:@std/jsonc@1.0.1", - "jsr:@std/path@1": "jsr:@std/path@1.0.2", - "jsr:@std/path@1.0.0-rc.1": "jsr:@std/path@1.0.0-rc.1", - "jsr:@std/path@^0.223": "jsr:@std/path@0.223.0", - "jsr:@std/path@^0.225.2": "jsr:@std/path@0.225.2", + "jsr:@std/io": "jsr:@std/io@0.224.9", "jsr:@std/path@^1.0.0": "jsr:@std/path@1.0.6", - "jsr:@std/path@^1.0.2": "jsr:@std/path@1.0.2", + "jsr:@std/path@^1.0.2": "jsr:@std/path@1.0.6", "jsr:@std/path@^1.0.6": "jsr:@std/path@1.0.6", - "jsr:@std/streams@^1.0.0": "jsr:@std/streams@1.0.6", - "jsr:@std/testing@^1.0.0": "jsr:@std/testing@1.0.3", - "jsr:@ts-morph/bootstrap@^0.24.0": "jsr:@ts-morph/bootstrap@0.24.0", - "jsr:@ts-morph/common@^0.24.0": "jsr:@ts-morph/common@0.24.0", - "npm:@openapitools/openapi-generator-cli@2.13.4": "npm:@openapitools/openapi-generator-cli@2.13.4_@nestjs+common@10.3.0__reflect-metadata@0.1.13__rxjs@7.8.1_axios@1.6.8_rxjs@7.8.1_reflect-metadata@0.1.13", + "jsr:@std/testing@^1.0.0": "jsr:@std/testing@1.0.0", "npm:@openapitools/openapi-generator-cli@2.14.0": "npm:@openapitools/openapi-generator-cli@2.14.0_@nestjs+common@10.4.3__reflect-metadata@0.1.13__rxjs@7.8.1_axios@1.7.7_rxjs@7.8.1_reflect-metadata@0.1.13", "npm:@types/node": "npm:@types/node@18.16.19", + "npm:axios-mock-adapter@^2.0.0": "npm:axios-mock-adapter@2.0.0_axios@1.7.7", "npm:axios@^1.7.3": "npm:axios@1.7.7", "npm:fetch-blob@^4.0.0": "npm:fetch-blob@4.0.0", "npm:fetch-mock@^11.1.3": "npm:fetch-mock@11.1.5", - "npm:typedoc@0.25.13": "npm:typedoc@0.25.13_typescript@5.4.5", - "npm:typescript@^5.4.5": "npm:typescript@5.6.2" + "npm:typedoc@0.26.7": "npm:typedoc@0.26.7_typescript@5.6.2" }, "jsr": { - "@david/code-block-writer@13.0.2": { - "integrity": "14dd3baaafa3a2dea8bf7dfbcddeccaa13e583da2d21d666c01dc6d681cd74ad" - }, - "@deno/cache-dir@0.10.3": { - "integrity": "eb022f84ecc49c91d9d98131c6e6b118ff63a29e343624d058646b9d50404776", - "dependencies": [ - "jsr:@std/fmt@^0.223", - "jsr:@std/fs@^0.223", - "jsr:@std/io@^0.223", - "jsr:@std/path@^0.223" - ] - }, - "@deno/dnt@0.41.3": { - "integrity": "b2ef2c8a5111eef86cb5bfcae103d6a2938e8e649e2461634a7befb7fc59d6d2", - "dependencies": [ - "jsr:@david/code-block-writer@^13.0.2", - "jsr:@deno/cache-dir@^0.10.3", - "jsr:@std/fmt@1", - "jsr:@std/fs@1", - "jsr:@std/path@1", - "jsr:@ts-morph/bootstrap@^0.24.0" - ] - }, - "@std/assert@0.223.0": { - "integrity": "eb8d6d879d76e1cc431205bd346ed4d88dc051c6366365b1af47034b0670be24" - }, - "@std/assert@0.226.0": { - "integrity": "0dfb5f7c7723c18cec118e080fec76ce15b4c31154b15ad2bd74822603ef75b3" - }, "@std/assert@1.0.6": { "integrity": "1904c05806a25d94fe791d6d883b685c9e2dcd60e4f9fc30f4fc5cf010c72207", "dependencies": [ "jsr:@std/internal@^1.0.4" ] }, - "@std/async@1.0.5": { - "integrity": "31d68214bfbb31bd4c6022401d484e3964147c76c9220098baa703a39b6c2da6" - }, - "@std/bytes@0.223.0": { - "integrity": "84b75052cd8680942c397c2631318772b295019098f40aac5c36cead4cba51a8" - }, "@std/bytes@1.0.2": { "integrity": "fbdee322bbd8c599a6af186a1603b3355e59a5fb1baa139f8f4c3c9a1b3e3d57" }, - "@std/data-structures@1.0.4": { - "integrity": "fa0e20c11eb9ba673417450915c750a0001405a784e2a4e0c3725031681684a0" - }, - "@std/fmt@0.223.0": { - "integrity": "6deb37794127dfc7d7bded2586b9fc6f5d50e62a8134846608baf71ffc1a5208" - }, - "@std/fmt@0.225.3": { - "integrity": "cb6ea567155f9865b80b502b2dde7671803eddd6dad743d8851d0de2c40bd349" - }, - "@std/fmt@1.0.2": { - "integrity": "87e9dfcdd3ca7c066e0c3c657c1f987c82888eb8103a3a3baa62684ffeb0f7a7" - }, - "@std/fs@0.223.0": { - "integrity": "3b4b0550b2c524cbaaa5a9170c90e96cbb7354e837ad1bdaf15fc9df1ae9c31c" - }, - "@std/fs@0.229.3": { - "integrity": "783bca21f24da92e04c3893c9e79653227ab016c48e96b3078377ebd5222e6eb", - "dependencies": [ - "jsr:@std/path@1.0.0-rc.1" - ] - }, - "@std/fs@1.0.1": { - "integrity": "d6914ca2c21abe591f733b31dbe6331e446815e513e2451b3b9e472daddfefcb", - "dependencies": [ - "jsr:@std/path@^1.0.2" - ] - }, "@std/fs@1.0.4": { "integrity": "2907d32d8d1d9e540588fd5fe0ec21ee638134bd51df327ad4e443aaef07123c", "dependencies": [ "jsr:@std/path@^1.0.6" ] }, - "@std/internal@1.0.0": { - "integrity": "ac6a6dfebf838582c4b4f61a6907374e27e05bedb6ce276e0f1608fe84e7cd9a" - }, "@std/internal@1.0.4": { "integrity": "62e8e4911527e5e4f307741a795c0b0a9e6958d0b3790716ae71ce085f755422" }, - "@std/io@0.223.0": { - "integrity": "2d8c3c2ab3a515619b90da2c6ff5ea7b75a94383259ef4d02116b228393f84f1", + "@std/io@0.224.9": { + "integrity": "4414664b6926f665102e73c969cfda06d2c4c59bd5d0c603fd4f1b1c840d6ee3", "dependencies": [ - "jsr:@std/assert@^0.223.0", - "jsr:@std/bytes@^0.223.0" - ] - }, - "@std/json@1.0.0": { - "integrity": "985c1e544918d42e4e84072fc739ac4a19c3a5093292c99742ffcdd03fb6a268", - "dependencies": [ - "jsr:@std/streams@^1.0.0" - ] - }, - "@std/jsonc@1.0.1": { - "integrity": "6b36956e2a7cbb08ca5ad7fbec72e661e6217c202f348496ea88747636710dda", - "dependencies": [ - "jsr:@std/json@^1.0.0" - ] - }, - "@std/path@0.223.0": { - "integrity": "593963402d7e6597f5a6e620931661053572c982fc014000459edc1f93cc3989", - "dependencies": [ - "jsr:@std/assert@^0.223.0" - ] - }, - "@std/path@0.225.2": { - "integrity": "0f2db41d36b50ef048dcb0399aac720a5348638dd3cb5bf80685bf2a745aa506", - "dependencies": [ - "jsr:@std/assert@^0.226.0" + "jsr:@std/bytes@^1.0.2" ] }, - "@std/path@1.0.0-rc.1": { - "integrity": "b8c00ae2f19106a6bb7cbf1ab9be52aa70de1605daeb2dbdc4f87a7cbaf10ff6" - }, - "@std/path@1.0.2": { - "integrity": "a452174603f8c620bd278a380c596437a9eef50c891c64b85812f735245d9ec7" - }, "@std/path@1.0.6": { "integrity": "ab2c55f902b380cf28e0eec501b4906e4c1960d13f00e11cfbcd21de15f18fed" }, - "@std/streams@1.0.6": { - "integrity": "022ed94e380d06b4d91c49eb70241b7289ab78b8c2b4c4bbb7eb265e4997c25c", - "dependencies": [ - "jsr:@std/bytes@^1.0.2" - ] - }, - "@std/testing@0.225.0": { - "integrity": "53ca3c47eb121acabda633fd50699c4b33da6a7ce3e5bb34d7277d15df5f0a6e", - "dependencies": [ - "jsr:@std/assert@^0.226.0", - "jsr:@std/fmt@^0.225.3", - "jsr:@std/fs@^0.229.1", - "jsr:@std/internal@^1.0.0", - "jsr:@std/path@^0.225.2" - ] - }, - "@std/testing@1.0.3": { - "integrity": "f98c2bee53860a5916727d7e7d3abe920dd6f9edace022e2d059f00d05c2cf42", + "@std/testing@1.0.0": { + "integrity": "27cfc06392c69c2acffe54e6d0bcb5f961cf193f519255372bd4fff1481bfef8", "dependencies": [ - "jsr:@std/assert@^1.0.6", - "jsr:@std/async@^1.0.5", - "jsr:@std/data-structures@^1.0.4", - "jsr:@std/fs@^1.0.4", - "jsr:@std/internal@^1.0.4", - "jsr:@std/path@^1.0.6" - ] - }, - "@ts-morph/bootstrap@0.24.0": { - "integrity": "a826a2ef7fa8a7c3f1042df2c034d20744d94da2ee32bf29275bcd4dffd3c060", - "dependencies": [ - "jsr:@ts-morph/common@^0.24.0" - ] - }, - "@ts-morph/common@0.24.0": { - "integrity": "12b625b8e562446ba658cdbe9ad77774b4bd96b992ae8bd34c60dbf24d06c1f3", - "dependencies": [ - "jsr:@std/fs@^0.229.3", - "jsr:@std/path@^0.225.2" + "jsr:@std/assert@^1.0.2", + "jsr:@std/fs@^1.0.1", + "jsr:@std/internal@^1.0.1", + "jsr:@std/path@^1.0.2" ] } }, "npm": { - "@babel/runtime@7.24.6": { - "integrity": "sha512-Ja18XcETdEl5mzzACGd+DKgaGJzPTCow7EglgwTmHdwokzDFYh/MHua6lU6DV/hjF2IaOJ4oX2nqnjG7RElKOw==", + "@babel/runtime@7.25.7": { + "integrity": "sha512-FjoyLe754PMiYsFaN5C94ttGiOmBNYTf6pLr4xXHAT5uctHb092PBszndLDR5XA/jghQvn4n7JMHl7dmTgbm9w==", "dependencies": { "regenerator-runtime": "regenerator-runtime@0.14.1" } @@ -223,14 +70,6 @@ "integrity": "sha512-Z7C/xXCiGWsg0KuKsHTKJxbWhpI3Vs5GwLfOean7MGyVFGqdRgBbAjOCh6u4bbjPc/8MJ2pZmK/0DLdCbivLDA==", "dependencies": {} }, - "@nestjs/axios@3.0.2_@nestjs+common@10.3.0__reflect-metadata@0.1.13__rxjs@7.8.1_axios@1.6.8_rxjs@7.8.1_reflect-metadata@0.1.13": { - "integrity": "sha512-Z6GuOUdNQjP7FX+OuV2Ybyamse+/e0BFdTWBX5JxpBDKA+YkdLynDgG6HTF04zy6e9zPa19UX0WA2VDoehwhXQ==", - "dependencies": { - "@nestjs/common": "@nestjs/common@10.3.0_reflect-metadata@0.1.13_rxjs@7.8.1", - "axios": "axios@1.6.8", - "rxjs": "rxjs@7.8.1" - } - }, "@nestjs/axios@3.0.3_@nestjs+common@10.4.3__reflect-metadata@0.1.13__rxjs@7.8.1_axios@1.7.7_rxjs@7.8.1_reflect-metadata@0.1.13": { "integrity": "sha512-h6TCn3yJwD6OKqqqfmtRS5Zo4E46Ip2n+gK1sqwzNBC+qxQ9xpCu+ODVRFur6V3alHSCSBxb3nNtt73VEdluyA==", "dependencies": { @@ -239,16 +78,6 @@ "rxjs": "rxjs@7.8.1" } }, - "@nestjs/common@10.3.0_reflect-metadata@0.1.13_rxjs@7.8.1": { - "integrity": "sha512-DGv34UHsZBxCM3H5QGE2XE/+oLJzz5+714JQjBhjD9VccFlQs3LRxo/epso4l7nJIiNlZkPyIUC8WzfU/5RTsQ==", - "dependencies": { - "iterare": "iterare@1.2.1", - "reflect-metadata": "reflect-metadata@0.1.13", - "rxjs": "rxjs@7.8.1", - "tslib": "tslib@2.6.2", - "uid": "uid@2.0.2" - } - }, "@nestjs/common@10.4.3_reflect-metadata@0.1.13_rxjs@7.8.1": { "integrity": "sha512-4hbLd3XIJubHSylYd/1WSi4VQvG68KM/ECYpMDqA3k3J1/T17SAg40sDoq3ZoO5OZgU0xuNyjuISdOTjs11qVg==", "dependencies": { @@ -259,20 +88,6 @@ "uid": "uid@2.0.2" } }, - "@nestjs/core@10.3.0_@nestjs+common@10.3.0__reflect-metadata@0.1.13__rxjs@7.8.1_reflect-metadata@0.1.13_rxjs@7.8.1": { - "integrity": "sha512-N06P5ncknW/Pm8bj964WvLIZn2gNhHliCBoAO1LeBvNImYkecqKcrmLbY49Fa1rmMfEM3MuBHeDys3edeuYAOA==", - "dependencies": { - "@nestjs/common": "@nestjs/common@10.3.0_reflect-metadata@0.1.13_rxjs@7.8.1", - "@nuxtjs/opencollective": "@nuxtjs/opencollective@0.3.2", - "fast-safe-stringify": "fast-safe-stringify@2.1.1", - "iterare": "iterare@1.2.1", - "path-to-regexp": "path-to-regexp@3.2.0", - "reflect-metadata": "reflect-metadata@0.1.13", - "rxjs": "rxjs@7.8.1", - "tslib": "tslib@2.6.2", - "uid": "uid@2.0.2" - } - }, "@nestjs/core@10.4.3_@nestjs+common@10.4.3__reflect-metadata@0.1.13__rxjs@7.8.1_reflect-metadata@0.1.13_rxjs@7.8.1": { "integrity": "sha512-6OQz+5C8mT8yRtfvE5pPCq+p6w5jDot+oQku1KzQ24ABn+lay1KGuJwcKZhdVNuselx+8xhdMxknZTA8wrGLIg==", "dependencies": { @@ -295,29 +110,6 @@ "node-fetch": "node-fetch@2.7.0" } }, - "@openapitools/openapi-generator-cli@2.13.4_@nestjs+common@10.3.0__reflect-metadata@0.1.13__rxjs@7.8.1_axios@1.6.8_rxjs@7.8.1_reflect-metadata@0.1.13": { - "integrity": "sha512-4JKyrk55ohQK2FcuZbPdNvxdyXD14jjOIvE8hYjJ+E1cHbRbfXQXbYnjTODFE52Gx8eAxz8C9icuhDYDLn7nww==", - "dependencies": { - "@nestjs/axios": "@nestjs/axios@3.0.2_@nestjs+common@10.3.0__reflect-metadata@0.1.13__rxjs@7.8.1_axios@1.6.8_rxjs@7.8.1_reflect-metadata@0.1.13", - "@nestjs/common": "@nestjs/common@10.3.0_reflect-metadata@0.1.13_rxjs@7.8.1", - "@nestjs/core": "@nestjs/core@10.3.0_@nestjs+common@10.3.0__reflect-metadata@0.1.13__rxjs@7.8.1_reflect-metadata@0.1.13_rxjs@7.8.1", - "@nuxtjs/opencollective": "@nuxtjs/opencollective@0.3.2", - "axios": "axios@1.6.8", - "chalk": "chalk@4.1.2", - "commander": "commander@8.3.0", - "compare-versions": "compare-versions@4.1.4", - "concurrently": "concurrently@6.5.1", - "console.table": "console.table@0.10.0", - "fs-extra": "fs-extra@10.1.0", - "glob": "glob@7.2.3", - "https-proxy-agent": "https-proxy-agent@7.0.4", - "inquirer": "inquirer@8.2.6", - "lodash": "lodash@4.17.21", - "reflect-metadata": "reflect-metadata@0.1.13", - "rxjs": "rxjs@7.8.1", - "tslib": "tslib@2.6.2" - } - }, "@openapitools/openapi-generator-cli@2.14.0_@nestjs+common@10.4.3__reflect-metadata@0.1.13__rxjs@7.8.1_axios@1.7.7_rxjs@7.8.1_reflect-metadata@0.1.13": { "integrity": "sha512-k+ioQLtXLXgNbhQbp1UOxtaUnnYTWwAPev88hP5qauFA+eq4NyeQGNojknFssXg2x0VT0TUGmU3PZ2DiQ70IVg==", "dependencies": { @@ -341,18 +133,75 @@ "tslib": "tslib@2.7.0" } }, + "@shikijs/core@1.21.0": { + "integrity": "sha512-zAPMJdiGuqXpZQ+pWNezQAk5xhzRXBNiECFPcJLtUdsFM3f//G95Z15EHTnHchYycU8kIIysqGgxp8OVSj1SPQ==", + "dependencies": { + "@shikijs/engine-javascript": "@shikijs/engine-javascript@1.21.0", + "@shikijs/engine-oniguruma": "@shikijs/engine-oniguruma@1.21.0", + "@shikijs/types": "@shikijs/types@1.21.0", + "@shikijs/vscode-textmate": "@shikijs/vscode-textmate@9.2.2", + "@types/hast": "@types/hast@3.0.4", + "hast-util-to-html": "hast-util-to-html@9.0.3" + } + }, + "@shikijs/engine-javascript@1.21.0": { + "integrity": "sha512-jxQHNtVP17edFW4/0vICqAVLDAxmyV31MQJL4U/Kg+heQALeKYVOWo0sMmEZ18FqBt+9UCdyqGKYE7bLRtk9mg==", + "dependencies": { + "@shikijs/types": "@shikijs/types@1.21.0", + "@shikijs/vscode-textmate": "@shikijs/vscode-textmate@9.2.2", + "oniguruma-to-js": "oniguruma-to-js@0.4.3" + } + }, + "@shikijs/engine-oniguruma@1.21.0": { + "integrity": "sha512-AIZ76XocENCrtYzVU7S4GY/HL+tgHGbVU+qhiDyNw1qgCA5OSi4B4+HY4BtAoJSMGuD/L5hfTzoRVbzEm2WTvg==", + "dependencies": { + "@shikijs/types": "@shikijs/types@1.21.0", + "@shikijs/vscode-textmate": "@shikijs/vscode-textmate@9.2.2" + } + }, + "@shikijs/types@1.21.0": { + "integrity": "sha512-tzndANDhi5DUndBtpojEq/42+dpUF2wS7wdCDQaFtIXm3Rd1QkrcVgSSRLOvEwexekihOXfbYJINW37g96tJRw==", + "dependencies": { + "@shikijs/vscode-textmate": "@shikijs/vscode-textmate@9.2.2", + "@types/hast": "@types/hast@3.0.4" + } + }, + "@shikijs/vscode-textmate@9.2.2": { + "integrity": "sha512-TMp15K+GGYrWlZM8+Lnj9EaHEFmOen0WJBrfa17hF7taDOYthuPPV0GWzfd/9iMij0akS/8Yw2ikquH7uVi/fg==", + "dependencies": {} + }, "@types/glob-to-regexp@0.4.4": { "integrity": "sha512-nDKoaKJYbnn1MZxUY0cA1bPmmgZbg0cTq7Rh13d0KWYNOiKbqoR+2d89SnRPszGh7ROzSwZ/GOjZ4jPbmmZ6Eg==", "dependencies": {} }, + "@types/hast@3.0.4": { + "integrity": "sha512-WPs+bbQw5aCj+x6laNGWLH3wviHtoCv/P3+otBhbOhJgG8qtpdAMlTCxLtsTWA7LH1Oh/bFCHsBn0TPS5m30EQ==", + "dependencies": { + "@types/unist": "@types/unist@3.0.3" + } + }, + "@types/mdast@4.0.4": { + "integrity": "sha512-kGaNbPh1k7AFzgpud/gMdvIm5xuECykRR+JnWKQno9TAXVa6WIVCGTPvYGekIDL4uwCZQSYbUxNBSb1aUo79oA==", + "dependencies": { + "@types/unist": "@types/unist@3.0.3" + } + }, "@types/node@18.16.19": { "integrity": "sha512-IXl7o+R9iti9eBW4Wg2hx1xQDig183jj7YLn8F7udNceyfkbn1ZxmzZXuak20gR40D7pIkIY1kYGx5VIGbaHKA==", "dependencies": {} }, + "@types/unist@3.0.3": { + "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==", + "dependencies": {} + }, + "@ungap/structured-clone@1.2.0": { + "integrity": "sha512-zuVdFrMJiuCDQUMCzQaD6KL28MjnqqN8XnAqiEq9PNm/hCPTSGfrXCOfwj1ow4LFb/tNymJPwsNbVePc1xFqrQ==", + "dependencies": {} + }, "agent-base@7.1.1": { "integrity": "sha512-H0TSyFNDMomMNJQBn8wFV5YC/2eJ+VXECwOadZJT554xP6cODZHPX3H9QMQECxvrgiSOP1pHjy1sMWQVYJOUOA==", "dependencies": { - "debug": "debug@4.3.5" + "debug": "debug@4.3.7" } }, "ansi-escapes@4.3.2": { @@ -365,32 +214,32 @@ "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", "dependencies": {} }, - "ansi-sequence-parser@1.1.1": { - "integrity": "sha512-vJXt3yiaUL4UU546s3rPXlsry/RnM730G1+HkpKE012AN0sx1eOrxSu95oKDIonskeLTijMgqWZ3uDEe3NFvyg==", - "dependencies": {} - }, "ansi-styles@4.3.0": { "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==", "dependencies": { "color-convert": "color-convert@2.0.1" } }, + "argparse@2.0.1": { + "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==", + "dependencies": {} + }, "asynckit@0.4.0": { "integrity": "sha512-Oei9OH4tRh0YqU3GxhX79dM/mwVgvbZJaSNaRk+bshkj0S5cfHcgYakreBjrHwatXKbz+IoIdYLxrKim2MjW0Q==", "dependencies": {} }, - "axios@1.6.8": { - "integrity": "sha512-v/ZHtJDU39mDpyBoFVkETcd/uNdxrWRrg3bKpOKzXFA6Bvqopts6ALSMU3y6ijYxbw2B+wPrIv46egTzJXCLGQ==", + "axios-mock-adapter@2.0.0_axios@1.7.7": { + "integrity": "sha512-D/K0J5Zm6KvaMTnsWrBQZWLzKN9GxUFZEa0mx2qeEHXDeTugCoplWehy8y36dj5vuSjhe1u/Dol8cZ8lzzmDew==", "dependencies": { - "follow-redirects": "follow-redirects@1.15.6", - "form-data": "form-data@4.0.0", - "proxy-from-env": "proxy-from-env@1.1.0" + "axios": "axios@1.7.7", + "fast-deep-equal": "fast-deep-equal@3.1.3", + "is-buffer": "is-buffer@2.0.5" } }, "axios@1.7.7": { "integrity": "sha512-S4kL7XrjgBmvdGut0sN3yJxqYzrDOnivkBiN0OFs6hLiUam3UPvswUo0kqGyhqUZGEOytHyumEdXsAkgCOUf3Q==", "dependencies": { - "follow-redirects": "follow-redirects@1.15.6", + "follow-redirects": "follow-redirects@1.15.9", "form-data": "form-data@4.0.0", "proxy-from-env": "proxy-from-env@1.1.0" } @@ -411,13 +260,6 @@ "readable-stream": "readable-stream@3.6.2" } }, - "brace-expansion@1.1.11": { - "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==", - "dependencies": { - "balanced-match": "balanced-match@1.0.2", - "concat-map": "concat-map@0.0.1" - } - }, "brace-expansion@2.0.1": { "integrity": "sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA==", "dependencies": { @@ -431,6 +273,10 @@ "ieee754": "ieee754@1.2.1" } }, + "ccount@2.0.1": { + "integrity": "sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg==", + "dependencies": {} + }, "chalk@4.1.2": { "integrity": "sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==", "dependencies": { @@ -438,6 +284,14 @@ "supports-color": "supports-color@7.2.0" } }, + "character-entities-html4@2.1.0": { + "integrity": "sha512-1v7fgQRj6hnSwFpq1Eu0ynr/CDEw0rXo2B61qXrLNdHZmPKgb7fqS1a2JwF0rISo9q77jDI8VMEHoApn8qDoZA==", + "dependencies": {} + }, + "character-entities-legacy@3.0.0": { + "integrity": "sha512-RpPp0asT/6ufRm//AJVwpViZbGM/MkjQFxJccQRHmISF/22NBtsHqAWmL+/pmkPWoIUJdWyeVleTl1wydHATVQ==", + "dependencies": {} + }, "chardet@0.7.0": { "integrity": "sha512-mT8iDcrh03qDGRRmoA2hmBJnxpllMR+0/0qlzjqZES6NdiWDcZkCNAk4rPFZ9Q85r27unkiNNg8ZOiwZXBHwcA==", "dependencies": {} @@ -484,6 +338,10 @@ "delayed-stream": "delayed-stream@1.0.0" } }, + "comma-separated-tokens@2.0.3": { + "integrity": "sha512-Fu4hJdvzeylCfQPp9SGWidpzrMs7tTrlu6Vb8XGaRGck8QSNZJJp538Wrb60Lax4fPwR64ViY468OIUTbRlGZg==", + "dependencies": {} + }, "commander@8.3.0": { "integrity": "sha512-OkTL9umf+He2DZkUq8f8J9of7yL6RJKI24dVITBmNfZBmri9zYZQrKkuXiKhyfPSu8tUhnVBB1iKXevvnlR4Ww==", "dependencies": {} @@ -492,10 +350,6 @@ "integrity": "sha512-FemMreK9xNyL8gQevsdRMrvO4lFCkQP7qbuktn1q8ndcNk1+0mz7lgE7b/sNvbhVgY4w6tMN1FDp6aADjqw2rw==", "dependencies": {} }, - "concat-map@0.0.1": { - "integrity": "sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg==", - "dependencies": {} - }, "concurrently@6.5.1": { "integrity": "sha512-FlSwNpGjWQfRwPLXvJ/OgysbBxPkWpiVjy1042b0U7on7S7qwwMIILRj7WTN1mTgqa582bG6NFuScOoh6Zgdag==", "dependencies": { @@ -503,7 +357,7 @@ "date-fns": "date-fns@2.30.0", "lodash": "lodash@4.17.21", "rxjs": "rxjs@6.6.7", - "spawn-command": "spawn-command@0.0.2-1", + "spawn-command": "spawn-command@0.0.2", "supports-color": "supports-color@8.1.1", "tree-kill": "tree-kill@1.2.2", "yargs": "yargs@16.2.0" @@ -522,13 +376,13 @@ "date-fns@2.30.0": { "integrity": "sha512-fnULvOpxnC5/Vg3NCiWelDsLiUc9bRwAPs/+LfTLNvetFCtCTN+yQz15C/fs4AwX1R9K5GLtLfn8QW+dWisaAw==", "dependencies": { - "@babel/runtime": "@babel/runtime@7.24.6" + "@babel/runtime": "@babel/runtime@7.25.7" } }, - "debug@4.3.5": { - "integrity": "sha512-pt0bNEmneDIvdL1Xsd9oDQ/wrQRkXDT4AUWlNZNPKvW5x/jyO9VFXkJUP07vQ2upmw5PlaITaPKc31jK13V+jg==", + "debug@4.3.7": { + "integrity": "sha512-Er2nc/H7RrMXZBFCEim6TCmMk02Z8vLC2Rbi1KEBggpo0fS6l0S1nnapwmIi3yW/+GOJap1Krg4w0Hg80oCqgQ==", "dependencies": { - "ms": "ms@2.1.2" + "ms": "ms@2.1.3" } }, "defaults@1.0.4": { @@ -545,6 +399,12 @@ "integrity": "sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA==", "dependencies": {} }, + "devlop@1.1.0": { + "integrity": "sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA==", + "dependencies": { + "dequal": "dequal@2.0.3" + } + }, "easy-table@1.1.0": { "integrity": "sha512-oq33hWOSSnl2Hoh00tZWaIPi1ievrD9aFG82/IgjlycAnW9hHx5PkJiXpxPsgEE+H7BsbVQXFVFST8TEXS6/pA==", "dependencies": { @@ -555,8 +415,12 @@ "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==", "dependencies": {} }, - "escalade@3.1.2": { - "integrity": "sha512-ErCHMCae19vR8vQGe50xIsVomy19rg6gFu3+r3jkEO46suLMWBksvVyoGgQV+jOfl84ZSOSlmv6Gxa89PmTGmA==", + "entities@4.5.0": { + "integrity": "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==", + "dependencies": {} + }, + "escalade@3.2.0": { + "integrity": "sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==", "dependencies": {} }, "escape-string-regexp@1.0.5": { @@ -571,6 +435,10 @@ "tmp": "tmp@0.0.33" } }, + "fast-deep-equal@3.1.3": { + "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==", + "dependencies": {} + }, "fast-safe-stringify@2.1.1": { "integrity": "sha512-W+KJc2dmILlPplD/H4K9l9LcAHAfPtP6BY84uVLXQ6Evcz9Lcg33Y2z1IVblT6xdY54PXYVHEv+0Wpq8Io6zkA==", "dependencies": {} @@ -597,10 +465,6 @@ "escape-string-regexp": "escape-string-regexp@1.0.5" } }, - "follow-redirects@1.15.6": { - "integrity": "sha512-wWN62YITEaOpSK584EZXJafH1AGpO8RVgElfkuXbTOrPX4fIfOyEpW/CsiNd8JdYrAoOvafRTOEnvsO++qCqFA==", - "dependencies": {} - }, "follow-redirects@1.15.9": { "integrity": "sha512-gew4GsXizNgdoRyqmyfMHyAmXsZDk6mHkSxZFCzW9gwlbtOW44CDtYavM+y+72qD/Vq2l550kMF52DT8fOLJqQ==", "dependencies": {} @@ -633,17 +497,6 @@ "integrity": "sha512-lkX1HJXwyMcprw/5YUZc2s7DrpAiHB21/V+E1rHUrVNokkvB6bqMzT0VfV6/86ZNabt1k14YOIaT7nDvOX3Iiw==", "dependencies": {} }, - "glob@7.2.3": { - "integrity": "sha512-nFR0zLpU2YCaRxwoCJvL6UvCH2JFyFVIvwTLsIf21AuHlMskA1hhTdk+LlYJtOlYt9v6dvszD2BGRqBL+iQK9Q==", - "dependencies": { - "fs.realpath": "fs.realpath@1.0.0", - "inflight": "inflight@1.0.6", - "inherits": "inherits@2.0.4", - "minimatch": "minimatch@3.1.2", - "once": "once@1.4.0", - "path-is-absolute": "path-is-absolute@1.0.1" - } - }, "glob@9.3.5": { "integrity": "sha512-e1LleDykUz2Iu+MTYdkSsuWX8lvAjAcs0Xef0lNIu0S2wOAzuTxCJtcd9S3cijlwYF18EsU3rzb8jPVobxDh9Q==", "dependencies": { @@ -661,18 +514,37 @@ "integrity": "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==", "dependencies": {} }, - "https-proxy-agent@7.0.4": { - "integrity": "sha512-wlwpilI7YdjSkWaQ/7omYBMTliDcmCN8OLihO6I9B86g06lMyAoqgoDpV0XqoaPOKj+0DIdAvnsWfyAAhmimcg==", + "hast-util-to-html@9.0.3": { + "integrity": "sha512-M17uBDzMJ9RPCqLMO92gNNUDuBSq10a25SDBI08iCCxmorf4Yy6sYHK57n9WAbRAAaU+DuR4W6GN9K4DFZesYg==", "dependencies": { - "agent-base": "agent-base@7.1.1", - "debug": "debug@4.3.5" + "@types/hast": "@types/hast@3.0.4", + "@types/unist": "@types/unist@3.0.3", + "ccount": "ccount@2.0.1", + "comma-separated-tokens": "comma-separated-tokens@2.0.3", + "hast-util-whitespace": "hast-util-whitespace@3.0.0", + "html-void-elements": "html-void-elements@3.0.0", + "mdast-util-to-hast": "mdast-util-to-hast@13.2.0", + "property-information": "property-information@6.5.0", + "space-separated-tokens": "space-separated-tokens@2.0.2", + "stringify-entities": "stringify-entities@4.0.4", + "zwitch": "zwitch@2.0.4" } }, + "hast-util-whitespace@3.0.0": { + "integrity": "sha512-88JUN06ipLwsnv+dVn+OIYOvAuvBMy/Qoi6O7mQHxdPXpjy+Cd6xRkWwux7DKO+4sYILtLBRIKgsdpS2gQc7qw==", + "dependencies": { + "@types/hast": "@types/hast@3.0.4" + } + }, + "html-void-elements@3.0.0": { + "integrity": "sha512-bEqo66MRXsUGxWHV5IP0PUiAWwoEjba4VCzg0LjFJBpchPaTfyfCKTG6bc5F8ucKec3q5y6qOdGyYTSBEvhCrg==", + "dependencies": {} + }, "https-proxy-agent@7.0.5": { "integrity": "sha512-1e4Wqeblerz+tMKPIq2EMGiiWW1dIjZOksyHWSUm1rmuvw/how9hBHZ38lAGj5ID4Ik6EdkOw7NmWPy6LAwalw==", "dependencies": { "agent-base": "agent-base@7.1.1", - "debug": "debug@4.3.5" + "debug": "debug@4.3.7" } }, "iconv-lite@0.4.24": { @@ -685,13 +557,6 @@ "integrity": "sha512-dcyqhDvX1C46lXZcVqCpK+FtMRQVdIMN6/Df5js2zouUsqG7I6sFxitIC+7KYK29KdXOLHdu9zL4sFnoVQnqaA==", "dependencies": {} }, - "inflight@1.0.6": { - "integrity": "sha512-k92I/b08q4wvFscXCLvqfsHCrjrF7yiXsQuIVvVE7N82W3+aqpzuUdBbfhWcy/FZR3/4IgflMgKLOsvPDrGCJA==", - "dependencies": { - "once": "once@1.4.0", - "wrappy": "wrappy@1.0.2" - } - }, "inherits@2.0.4": { "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==", "dependencies": {} @@ -716,6 +581,10 @@ "wrap-ansi": "wrap-ansi@6.2.0" } }, + "is-buffer@2.0.5": { + "integrity": "sha512-i2R6zNFDwgEHJyQUtJEk0XFi1i0dPFn/oqjK3/vPCcDeJvW5NQ83V8QbicfF1SupOaB0h8ntgBC2YiE7dfyctQ==", + "dependencies": {} + }, "is-fullwidth-code-point@3.0.0": { "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==", "dependencies": {} @@ -736,10 +605,6 @@ "integrity": "sha512-RKYVTCjAnRthyJes037NX/IiqeidgN1xc3j1RjFfECFp28A1GVwK9nA+i0rJPaHqSZwygLzRnFlzUuHFoWWy+Q==", "dependencies": {} }, - "jsonc-parser@3.2.1": { - "integrity": "sha512-AilxAyFOAcK5wA1+LeaySVBrHsGQvUFCDWXKpZjzaL0PqW+xfBOttn8GNtWKFWqneyMZj41MWF9Kl6iPWLwgOA==", - "dependencies": {} - }, "jsonfile@6.1.0": { "integrity": "sha512-5dgndWOriYSm5cnYaJNhalLNDKOqFwyDB/rr1E9ZsGciGvKPs8R2xYGCacuf3z6K1YKDz182fd+fY3cn3pMqXQ==", "dependencies": { @@ -747,6 +612,12 @@ "universalify": "universalify@2.0.1" } }, + "linkify-it@5.0.0": { + "integrity": "sha512-5aHCbzQRADcdP+ATqnDuhhJ/MRIqDkZX5pyjFHRRysS8vZ5AbqGEoFIb6pYHPZ+L/OC2Lc+xT8uHVVR5CAK/wQ==", + "dependencies": { + "uc.micro": "uc.micro@2.1.0" + } + }, "lodash@4.17.21": { "integrity": "sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg==", "dependencies": {} @@ -766,8 +637,60 @@ "integrity": "sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==", "dependencies": {} }, - "marked@4.3.0": { - "integrity": "sha512-PRsaiG84bK+AMvxziE/lCFss8juXjNaWzVbN5tXAm4XjeaS9NAHhop+PjQxz2A9h8Q4M/xGmzP8vqNwy6JeK0A==", + "markdown-it@14.1.0": { + "integrity": "sha512-a54IwgWPaeBCAAsv13YgmALOF1elABB08FxO9i+r4VFk5Vl4pKokRPeX8u5TCgSsPi6ec1otfLjdOpVcgbpshg==", + "dependencies": { + "argparse": "argparse@2.0.1", + "entities": "entities@4.5.0", + "linkify-it": "linkify-it@5.0.0", + "mdurl": "mdurl@2.0.0", + "punycode.js": "punycode.js@2.3.1", + "uc.micro": "uc.micro@2.1.0" + } + }, + "mdast-util-to-hast@13.2.0": { + "integrity": "sha512-QGYKEuUsYT9ykKBCMOEDLsU5JRObWQusAolFMeko/tYPufNkRffBAQjIE+99jbA87xv6FgmjLtwjh9wBWajwAA==", + "dependencies": { + "@types/hast": "@types/hast@3.0.4", + "@types/mdast": "@types/mdast@4.0.4", + "@ungap/structured-clone": "@ungap/structured-clone@1.2.0", + "devlop": "devlop@1.1.0", + "micromark-util-sanitize-uri": "micromark-util-sanitize-uri@2.0.0", + "trim-lines": "trim-lines@3.0.1", + "unist-util-position": "unist-util-position@5.0.0", + "unist-util-visit": "unist-util-visit@5.0.0", + "vfile": "vfile@6.0.3" + } + }, + "mdurl@2.0.0": { + "integrity": "sha512-Lf+9+2r+Tdp5wXDXC4PcIBjTDtq4UKjCPMQhKIuzpJNW0b96kVqSwW0bT7FhRSfmAiFYgP+SCRvdrDozfh0U5w==", + "dependencies": {} + }, + "micromark-util-character@2.1.0": { + "integrity": "sha512-KvOVV+X1yLBfs9dCBSopq/+G1PcgT3lAK07mC4BzXi5E7ahzMAF8oIupDDJ6mievI6F+lAATkbQQlQixJfT3aQ==", + "dependencies": { + "micromark-util-symbol": "micromark-util-symbol@2.0.0", + "micromark-util-types": "micromark-util-types@2.0.0" + } + }, + "micromark-util-encode@2.0.0": { + "integrity": "sha512-pS+ROfCXAGLWCOc8egcBvT0kf27GoWMqtdarNfDcjb6YLuV5cM3ioG45Ys2qOVqeqSbjaKg72vU+Wby3eddPsA==", + "dependencies": {} + }, + "micromark-util-sanitize-uri@2.0.0": { + "integrity": "sha512-WhYv5UEcZrbAtlsnPuChHUAsu/iBPOVaEVsntLBIdpibO0ddy8OzavZz3iL2xVvBZOpolujSliP65Kq0/7KIYw==", + "dependencies": { + "micromark-util-character": "micromark-util-character@2.1.0", + "micromark-util-encode": "micromark-util-encode@2.0.0", + "micromark-util-symbol": "micromark-util-symbol@2.0.0" + } + }, + "micromark-util-symbol@2.0.0": { + "integrity": "sha512-8JZt9ElZ5kyTnO94muPxIGS8oyElRJaiJO8EzV6ZSyGQ1Is8xwl4Q45qU5UOg+bGH4AikWziz0iN4sFLWs8PGw==", + "dependencies": {} + }, + "micromark-util-types@2.0.0": { + "integrity": "sha512-oNh6S2WMHWRZrmutsRmDDfkzKtxF+bc2VxLC9dvtrDIRFln627VsFP6fLMgTryGDljgLPjkrzQSDcPrjPyDJ5w==", "dependencies": {} }, "mime-db@1.52.0": { @@ -784,12 +707,6 @@ "integrity": "sha512-OqbOk5oEQeAZ8WXWydlu9HJjz9WVdEIvamMCcXmuqUYjTknH/sqsWvhQ3vgwKFRR1HpjvNBKQ37nbJgYzGqGcg==", "dependencies": {} }, - "minimatch@3.1.2": { - "integrity": "sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw==", - "dependencies": { - "brace-expansion": "brace-expansion@1.1.11" - } - }, "minimatch@8.0.4": { "integrity": "sha512-W0Wvr9HyFXZRGIDgCicunpQ299OKXs9RgZfaukz4qAW/pJhcpUfupc9c+OObPOFueNy8VSrZgEmDtk6Kh4WzDA==", "dependencies": { @@ -810,8 +727,8 @@ "integrity": "sha512-qOOzS1cBTWYF4BH8fVePDBOO9iptMnGUEZwNc/cMWnTV2nVLZ7VoNWEPHkYczZA0pdoA7dl6e7FL659nX9S2aw==", "dependencies": {} }, - "ms@2.1.2": { - "integrity": "sha512-sGkPx+VjMtmA6MX27oA4FBFELFCZZ4S4XqeGOXCv68tT+jb3vk/RyaKWP0PTKyWtmLSM0b+adUTEvbs1PEaH2w==", + "ms@2.1.3": { + "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==", "dependencies": {} }, "mute-stream@0.0.8": { @@ -828,18 +745,18 @@ "whatwg-url": "whatwg-url@5.0.0" } }, - "once@1.4.0": { - "integrity": "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==", - "dependencies": { - "wrappy": "wrappy@1.0.2" - } - }, "onetime@5.1.2": { "integrity": "sha512-kbpaSSGJTWdAY5KPVeMOKXSrPtr8C8C7wodJbcsd51jRnmD+GZu8Y0VoU6Dm5Z4vWr0Ig/1NKuWRKf7j5aaYSg==", "dependencies": { "mimic-fn": "mimic-fn@2.1.0" } }, + "oniguruma-to-js@0.4.3": { + "integrity": "sha512-X0jWUcAlxORhOqqBREgPMgnshB7ZGYszBNspP+tS9hPD3l13CdaXcHbgImoHUHlrvGx/7AvFEkTRhAGYh+jzjQ==", + "dependencies": { + "regex": "regex@4.3.3" + } + }, "ora@5.4.1": { "integrity": "sha512-5b6Y85tPxZZ7QytO+BQzysW31HJku27cRIlkbAXaNx+BdcVi+LlRFmVXzeF6a7JCwJpyw5c4b+YSVImQIrBpuQ==", "dependencies": { @@ -858,10 +775,6 @@ "integrity": "sha512-D2FR03Vir7FIu45XBY20mTb+/ZSWB00sjU9jdQXt83gDrI4Ztz5Fs7/yy74g2N5SVQY4xY1qDr4rNddwYRVX0g==", "dependencies": {} }, - "path-is-absolute@1.0.1": { - "integrity": "sha512-AVbw3UJ2e9bq64vSaS9Am0fje1Pa8pbGqTTsmXfaIiMpnr5DlDhfJOuLj9Sf95ZPVDAUerDfEk88MPmPe7UCQg==", - "dependencies": {} - }, "path-scurry@1.11.1": { "integrity": "sha512-Xa4Nw17FS9ApQFJ9umLiJS4orGjm7ZzwUrwamcGQuHSzDyth9boKDaycYdDcZDuqYATXw4HFXgaqWTctW/v1HA==", "dependencies": { @@ -869,18 +782,22 @@ "minipass": "minipass@7.1.2" } }, - "path-to-regexp@3.2.0": { - "integrity": "sha512-jczvQbCUS7XmS7o+y1aEO9OBVFeZBQ1MDSEqmO7xSoPgOPoowY/SxLpZ6Vh97/8qHZOteiCKb7gkG9gA2ZUxJA==", - "dependencies": {} - }, "path-to-regexp@3.3.0": { "integrity": "sha512-qyCH421YQPS2WFDxDjftfc1ZR5WKQzVzqsp4n9M2kQhVOo/ByahFoUNJfl58kOcEGfQ//7weFTDhm+ss8Ecxgw==", "dependencies": {} }, + "property-information@6.5.0": { + "integrity": "sha512-PgTgs/BlvHxOu8QuEN7wi5A0OmXaBcHpmCSTehcs6Uuu9IkDIEo13Hy7n898RHfrQ49vKCoGeWZSaAK01nwVig==", + "dependencies": {} + }, "proxy-from-env@1.1.0": { "integrity": "sha512-D+zkORCbA9f1tdWRK0RaCR3GPv50cMxcrz4X8k5LTSUD1Dkw47mKJEZQNunItRTkWwgtaUSo1RVFRIG9ZXiFYg==", "dependencies": {} }, + "punycode.js@2.3.1": { + "integrity": "sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA==", + "dependencies": {} + }, "readable-stream@3.6.2": { "integrity": "sha512-9u/sniCrY3D5WdsERHzHE4G2YCXqoG5FTHUiCC4SIbr6XcLZBY05ya9EKjYek9O5xOAwjGq+1JdGBAS7Q9ScoA==", "dependencies": { @@ -897,6 +814,10 @@ "integrity": "sha512-dYnhHh0nJoMfnkZs6GmmhFknAGRrLznOu5nc9ML+EJxGvrx6H7teuevqVqCuPcPK//3eDrrjQhehXVx9cnkGdw==", "dependencies": {} }, + "regex@4.3.3": { + "integrity": "sha512-r/AadFO7owAq1QJVeZ/nq9jNS1vyZt+6t1p/E59B56Rn2GCya+gr1KSyOzNL/er+r+B7phv5jG2xU2Nz1YkmJg==", + "dependencies": {} + }, "regexparam@3.0.0": { "integrity": "sha512-RSYAtP31mvYLkAHrOlh25pCNQ5hWnT106VukGaaFfuJrZFkGRX5GhUAdPqpSDXxOhA2c4akmRuplv1mRqnBn6Q==", "dependencies": {} @@ -925,7 +846,7 @@ "rxjs@7.8.1": { "integrity": "sha512-AA3TVj+0A2iuIoQkWEK/tqFjBq2j+6PO6Y0zJcvzLAFhEFIO3HL0vls9hWLncZbAAbK0mar7oZ4V079I/qPMxg==", "dependencies": { - "tslib": "tslib@2.6.2" + "tslib": "tslib@2.7.0" } }, "safe-buffer@5.2.1": { @@ -936,21 +857,27 @@ "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==", "dependencies": {} }, - "shiki@0.14.7": { - "integrity": "sha512-dNPAPrxSc87ua2sKJ3H5dQ/6ZaY8RNnaAqK+t0eG7p0Soi2ydiqbGOTaZCqaYvA/uZYfS1LJnemt3Q+mSfcPCg==", + "shiki@1.21.0": { + "integrity": "sha512-apCH5BoWTrmHDPGgg3RF8+HAAbEL/CdbYr8rMw7eIrdhCkZHdVGat5mMNlRtd1erNG01VPMIKHNQ0Pj2HMAiog==", "dependencies": { - "ansi-sequence-parser": "ansi-sequence-parser@1.1.1", - "jsonc-parser": "jsonc-parser@3.2.1", - "vscode-oniguruma": "vscode-oniguruma@1.7.0", - "vscode-textmate": "vscode-textmate@8.0.0" + "@shikijs/core": "@shikijs/core@1.21.0", + "@shikijs/engine-javascript": "@shikijs/engine-javascript@1.21.0", + "@shikijs/engine-oniguruma": "@shikijs/engine-oniguruma@1.21.0", + "@shikijs/types": "@shikijs/types@1.21.0", + "@shikijs/vscode-textmate": "@shikijs/vscode-textmate@9.2.2", + "@types/hast": "@types/hast@3.0.4" } }, "signal-exit@3.0.7": { "integrity": "sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ==", "dependencies": {} }, - "spawn-command@0.0.2-1": { - "integrity": "sha512-n98l9E2RMSJ9ON1AKisHzz7V42VDiBQGY6PB1BwRglz99wpVsSuGzQ+jOi6lFXBGVTCrRpltvjm+/XA+tpeJrg==", + "space-separated-tokens@2.0.2": { + "integrity": "sha512-PEGlAwrG8yXGXRjW32fGbg66JAlOAwbObuqVoJpv/mRgoWDQfgH1wDPvtzWyUSNAXBGSk8h755YDbbcEy3SH2Q==", + "dependencies": {} + }, + "spawn-command@0.0.2": { + "integrity": "sha512-zC8zGoGkmc8J9ndvml8Xksr1Amk9qBujgbF0JAIWO7kXr43w0h/0GJNM/Vustixu+YE8N/MTrQ7N31FvHUACxQ==", "dependencies": {} }, "string-width@4.2.3": { @@ -967,6 +894,13 @@ "safe-buffer": "safe-buffer@5.2.1" } }, + "stringify-entities@4.0.4": { + "integrity": "sha512-IwfBptatlO+QCJUo19AqvrPNqlVMpW9YEL2LIVY+Rpv2qsjCGxaDLNRgeGsQWJhfItebuJhsGSLjaBbNSQ+ieg==", + "dependencies": { + "character-entities-html4": "character-entities-html4@2.1.0", + "character-entities-legacy": "character-entities-legacy@3.0.0" + } + }, "strip-ansi@6.0.1": { "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", "dependencies": { @@ -1003,12 +937,12 @@ "integrity": "sha512-L0Orpi8qGpRG//Nd+H90vFB+3iHnue1zSSGmNOOCh1GLJ7rUKVwV2HvijphGQS2UmhUZewS9VgvxYIdgr+fG1A==", "dependencies": {} }, - "tslib@1.14.1": { - "integrity": "sha512-Xni35NKzjgMrwevysHTCArtLDpPvye8zV/0E4EyYn43P7/7qvQwPh9BGkHewbMulVntbigmcT7rdX3BNo9wRJg==", + "trim-lines@3.0.1": { + "integrity": "sha512-kRj8B+YHZCc9kQYdWfJB2/oUl9rA99qbowYYBtr4ui4mZyAQ2JpvVBd/6U2YloATfqBhBTSMhTpgBHtU0Mf3Rg==", "dependencies": {} }, - "tslib@2.6.2": { - "integrity": "sha512-AEYxH93jGFPn/a2iVAwW87VuUIkR1FVUKB77NwMF7nBTDkDrrT/Hpt/IrCJ0QXhW27jTBDcf5ZY7w6RiqTMw2Q==", + "tslib@1.14.1": { + "integrity": "sha512-Xni35NKzjgMrwevysHTCArtLDpPvye8zV/0E4EyYn43P7/7qvQwPh9BGkHewbMulVntbigmcT7rdX3BNo9wRJg==", "dependencies": {} }, "tslib@2.7.0": { @@ -1019,30 +953,64 @@ "integrity": "sha512-t0rzBq87m3fVcduHDUFhKmyyX+9eo6WQjZvf51Ea/M0Q7+T374Jp1aUiyUl0GKxp8M/OETVHSDvmkyPgvX+X2w==", "dependencies": {} }, - "typedoc@0.25.13_typescript@5.4.5": { - "integrity": "sha512-pQqiwiJ+Z4pigfOnnysObszLiU3mVLWAExSPf+Mu06G/qsc3wzbuM56SZQvONhHLncLUhYzOVkjFFpFfL5AzhQ==", + "typedoc@0.26.7_typescript@5.6.2": { + "integrity": "sha512-gUeI/Wk99vjXXMi8kanwzyhmeFEGv1LTdTQsiyIsmSYsBebvFxhbcyAx7Zjo4cMbpLGxM4Uz3jVIjksu/I2v6Q==", "dependencies": { "lunr": "lunr@2.3.9", - "marked": "marked@4.3.0", + "markdown-it": "markdown-it@14.1.0", "minimatch": "minimatch@9.0.5", - "shiki": "shiki@0.14.7", - "typescript": "typescript@5.4.5" + "shiki": "shiki@1.21.0", + "typescript": "typescript@5.6.2", + "yaml": "yaml@2.5.1" } }, - "typescript@5.4.5": { - "integrity": "sha512-vcI4UpRgg81oIRUFwR0WSIHKt11nJ7SAVlYNIu+QpqeyXP+gpQJy/Z4+F0aGxSE4MqwjyXvW/TzgkLAx2AGHwQ==", - "dependencies": {} - }, "typescript@5.6.2": { "integrity": "sha512-NW8ByodCSNCwZeghjN3o+JX5OFH0Ojg6sadjEKY4huZ52TqbJTJnDo5+Tw98lSy63NZvi4n+ez5m2u5d4PkZyw==", "dependencies": {} }, + "uc.micro@2.1.0": { + "integrity": "sha512-ARDJmphmdvUk6Glw7y9DQ2bFkKBHwQHLi2lsaH6PPmz/Ka9sFOBsBluozhDltWmnv9u/cF6Rt87znRTPV+yp/A==", + "dependencies": {} + }, "uid@2.0.2": { "integrity": "sha512-u3xV3X7uzvi5b1MncmZo3i2Aw222Zk1keqLA1YkHldREkAhAqi65wuPfe7lHx8H/Wzy+8CE7S7uS3jekIM5s8g==", "dependencies": { "@lukeed/csprng": "@lukeed/csprng@1.1.0" } }, + "unist-util-is@6.0.0": { + "integrity": "sha512-2qCTHimwdxLfz+YzdGfkqNlH0tLi9xjTnHddPmJwtIG9MGsdbutfTc4P+haPD7l7Cjxf/WZj+we5qfVPvvxfYw==", + "dependencies": { + "@types/unist": "@types/unist@3.0.3" + } + }, + "unist-util-position@5.0.0": { + "integrity": "sha512-fucsC7HjXvkB5R3kTCO7kUjRdrS0BJt3M/FPxmHMBOm8JQi2BsHAHFsy27E0EolP8rp0NzXsJ+jNPyDWvOJZPA==", + "dependencies": { + "@types/unist": "@types/unist@3.0.3" + } + }, + "unist-util-stringify-position@4.0.0": { + "integrity": "sha512-0ASV06AAoKCDkS2+xw5RXJywruurpbC4JZSm7nr7MOt1ojAzvyyaO+UxZf18j8FCF6kmzCZKcAgN/yu2gm2XgQ==", + "dependencies": { + "@types/unist": "@types/unist@3.0.3" + } + }, + "unist-util-visit-parents@6.0.1": { + "integrity": "sha512-L/PqWzfTP9lzzEa6CKs0k2nARxTdZduw3zyh8d2NVBnsyvHjSX4TWse388YrrQKbvI8w20fGjGlhgT96WwKykw==", + "dependencies": { + "@types/unist": "@types/unist@3.0.3", + "unist-util-is": "unist-util-is@6.0.0" + } + }, + "unist-util-visit@5.0.0": { + "integrity": "sha512-MR04uvD+07cwl/yhVuVWAtw+3GOR/knlL55Nd/wAdblk27GCVt3lqpTivy/tkJcZoNPzTwS1Y+KMojlLDhoTzg==", + "dependencies": { + "@types/unist": "@types/unist@3.0.3", + "unist-util-is": "unist-util-is@6.0.0", + "unist-util-visit-parents": "unist-util-visit-parents@6.0.1" + } + }, "universalify@2.0.1": { "integrity": "sha512-gptHNQghINnc/vTGIk0SOFGFNXw7JVrlRUtConJRlvaw6DuX0wO5Jeko9sWrMBhh+PsYAZ7oXAiOnf/UKogyiw==", "dependencies": {} @@ -1051,13 +1019,19 @@ "integrity": "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==", "dependencies": {} }, - "vscode-oniguruma@1.7.0": { - "integrity": "sha512-L9WMGRfrjOhgHSdOYgCt/yRMsXzLDJSL7BPrOZt73gU0iWO4mpqzqQzOz5srxqTvMBaR0XZTSrVWo4j55Rc6cA==", - "dependencies": {} + "vfile-message@4.0.2": { + "integrity": "sha512-jRDZ1IMLttGj41KcZvlrYAaI3CfqpLpfpf+Mfig13viT6NKvRzWZ+lXz0Y5D60w6uJIBAOGq9mSHf0gktF0duw==", + "dependencies": { + "@types/unist": "@types/unist@3.0.3", + "unist-util-stringify-position": "unist-util-stringify-position@4.0.0" + } }, - "vscode-textmate@8.0.0": { - "integrity": "sha512-AFbieoL7a5LMqcnOF04ji+rpXadgOXnZsxQr//r83kLPr7biP7am3g9zbaZIaBGwBRWeSvoMD4mgPdX3e4NWBg==", - "dependencies": {} + "vfile@6.0.3": { + "integrity": "sha512-KzIbH/9tXat2u30jf+smMwFCsno4wHVdNmzFyL+T/L3UGqqk6JKfVqOFOZEpZSHADH1k40ab6NUIXZq422ov3Q==", + "dependencies": { + "@types/unist": "@types/unist@3.0.3", + "vfile-message": "vfile-message@4.0.2" + } }, "wcwidth@1.0.1": { "integrity": "sha512-XHPEwS0q6TaxcvG85+8EYkbiCux2XtWG2mkc47Ng2A77BQu9+DqIOJldST4HgPkuea7dvKSj5VgX3P1d4rW8Tg==", @@ -1092,14 +1066,14 @@ "strip-ansi": "strip-ansi@6.0.1" } }, - "wrappy@1.0.2": { - "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==", - "dependencies": {} - }, "y18n@5.0.8": { "integrity": "sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==", "dependencies": {} }, + "yaml@2.5.1": { + "integrity": "sha512-bLQOjaX/ADgQ20isPJRvF0iRUHIxVhYvr53Of7wGcWlO2jvtUlH5m87DsmulFVxRpNLOnI4tB6p/oh8D7kpn9Q==", + "dependencies": {} + }, "yargs-parser@20.2.9": { "integrity": "sha512-y11nGElTIV+CT3Zv9t7VKl+Q3hTQoT9a1Qzezhhl6Rp21gJ/IVTW7Z3y9EWXhuUBC2Shnf+DX0antecpAwSP8w==", "dependencies": {} @@ -1108,17 +1082,23 @@ "integrity": "sha512-D1mvvtDG0L5ft/jGWkLpG1+m0eQxOfaBvTNELraWj22wSVUMWxZUvYgJYcKh6jGGIkJFhH4IZPQhR4TKpc8mBw==", "dependencies": { "cliui": "cliui@7.0.4", - "escalade": "escalade@3.1.2", + "escalade": "escalade@3.2.0", "get-caller-file": "get-caller-file@2.0.5", "require-directory": "require-directory@2.1.1", "string-width": "string-width@4.2.3", "y18n": "y18n@5.0.8", "yargs-parser": "yargs-parser@20.2.9" } + }, + "zwitch@2.0.4": { + "integrity": "sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A==", + "dependencies": {} } } }, - "remote": {}, + "remote": { + "https://deno.land/x/keypress@0.0.11/mod.ts": "22fe0ea62136f3015149c639f891076a5b2312c0b8974c4a2bd8acaaded61c61" + }, "workspace": { "dependencies": [ "jsr:@deno/dnt@^0.41.3", From 6fe02bf272b71a1f743c6b0aee7717761628640f Mon Sep 17 00:00:00 2001 From: Joscha Feth Date: Tue, 8 Oct 2024 11:53:42 +0100 Subject: [PATCH 9/9] chore: declutter lock file --- deno.lock | 108 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 107 insertions(+), 1 deletion(-) diff --git a/deno.lock b/deno.lock index 8098f90..9dde431 100644 --- a/deno.lock +++ b/deno.lock @@ -2,35 +2,103 @@ "version": "3", "packages": { "specifiers": { + "jsr:@david/code-block-writer@^13.0.2": "jsr:@david/code-block-writer@13.0.2", + "jsr:@deno/cache-dir@^0.10.3": "jsr:@deno/cache-dir@0.10.3", + "jsr:@deno/dnt@^0.41.3": "jsr:@deno/dnt@0.41.3", + "jsr:@std/assert@^0.223.0": "jsr:@std/assert@0.223.0", + "jsr:@std/assert@^0.226.0": "jsr:@std/assert@0.226.0", "jsr:@std/assert@^1.0.0": "jsr:@std/assert@1.0.6", "jsr:@std/assert@^1.0.2": "jsr:@std/assert@1.0.6", + "jsr:@std/bytes@^0.223.0": "jsr:@std/bytes@0.223.0", "jsr:@std/bytes@^1.0.2": "jsr:@std/bytes@1.0.2", + "jsr:@std/fmt@1": "jsr:@std/fmt@1.0.2", + "jsr:@std/fmt@^0.223": "jsr:@std/fmt@0.223.0", + "jsr:@std/fs@1": "jsr:@std/fs@1.0.4", + "jsr:@std/fs@^0.223": "jsr:@std/fs@0.223.0", + "jsr:@std/fs@^0.229.3": "jsr:@std/fs@0.229.3", + "jsr:@std/fs@^1.0.0": "jsr:@std/fs@1.0.4", "jsr:@std/fs@^1.0.1": "jsr:@std/fs@1.0.4", "jsr:@std/internal@^1.0.1": "jsr:@std/internal@1.0.4", "jsr:@std/internal@^1.0.4": "jsr:@std/internal@1.0.4", "jsr:@std/io": "jsr:@std/io@0.224.9", + "jsr:@std/io@^0.223": "jsr:@std/io@0.223.0", + "jsr:@std/jsonc@^1.0.0": "jsr:@std/jsonc@1.0.1", + "jsr:@std/path@1": "jsr:@std/path@1.0.6", + "jsr:@std/path@1.0.0-rc.1": "jsr:@std/path@1.0.0-rc.1", + "jsr:@std/path@^0.223": "jsr:@std/path@0.223.0", + "jsr:@std/path@^0.225.2": "jsr:@std/path@0.225.2", "jsr:@std/path@^1.0.0": "jsr:@std/path@1.0.6", "jsr:@std/path@^1.0.2": "jsr:@std/path@1.0.6", "jsr:@std/path@^1.0.6": "jsr:@std/path@1.0.6", "jsr:@std/testing@^1.0.0": "jsr:@std/testing@1.0.0", + "jsr:@ts-morph/bootstrap@^0.24.0": "jsr:@ts-morph/bootstrap@0.24.0", + "jsr:@ts-morph/common@^0.24.0": "jsr:@ts-morph/common@0.24.0", "npm:@openapitools/openapi-generator-cli@2.14.0": "npm:@openapitools/openapi-generator-cli@2.14.0_@nestjs+common@10.4.3__reflect-metadata@0.1.13__rxjs@7.8.1_axios@1.7.7_rxjs@7.8.1_reflect-metadata@0.1.13", "npm:@types/node": "npm:@types/node@18.16.19", "npm:axios-mock-adapter@^2.0.0": "npm:axios-mock-adapter@2.0.0_axios@1.7.7", "npm:axios@^1.7.3": "npm:axios@1.7.7", "npm:fetch-blob@^4.0.0": "npm:fetch-blob@4.0.0", "npm:fetch-mock@^11.1.3": "npm:fetch-mock@11.1.5", - "npm:typedoc@0.26.7": "npm:typedoc@0.26.7_typescript@5.6.2" + "npm:typedoc@0.26.7": "npm:typedoc@0.26.7_typescript@5.6.2", + "npm:typescript@^5.4.5": "npm:typescript@5.6.2" }, "jsr": { + "@david/code-block-writer@13.0.2": { + "integrity": "14dd3baaafa3a2dea8bf7dfbcddeccaa13e583da2d21d666c01dc6d681cd74ad" + }, + "@deno/cache-dir@0.10.3": { + "integrity": "eb022f84ecc49c91d9d98131c6e6b118ff63a29e343624d058646b9d50404776", + "dependencies": [ + "jsr:@std/fmt@^0.223", + "jsr:@std/fs@^0.223", + "jsr:@std/io@^0.223", + "jsr:@std/path@^0.223" + ] + }, + "@deno/dnt@0.41.3": { + "integrity": "b2ef2c8a5111eef86cb5bfcae103d6a2938e8e649e2461634a7befb7fc59d6d2", + "dependencies": [ + "jsr:@david/code-block-writer@^13.0.2", + "jsr:@deno/cache-dir@^0.10.3", + "jsr:@std/fmt@1", + "jsr:@std/fs@1", + "jsr:@std/path@1", + "jsr:@ts-morph/bootstrap@^0.24.0" + ] + }, + "@std/assert@0.223.0": { + "integrity": "eb8d6d879d76e1cc431205bd346ed4d88dc051c6366365b1af47034b0670be24" + }, + "@std/assert@0.226.0": { + "integrity": "0dfb5f7c7723c18cec118e080fec76ce15b4c31154b15ad2bd74822603ef75b3" + }, "@std/assert@1.0.6": { "integrity": "1904c05806a25d94fe791d6d883b685c9e2dcd60e4f9fc30f4fc5cf010c72207", "dependencies": [ "jsr:@std/internal@^1.0.4" ] }, + "@std/bytes@0.223.0": { + "integrity": "84b75052cd8680942c397c2631318772b295019098f40aac5c36cead4cba51a8" + }, "@std/bytes@1.0.2": { "integrity": "fbdee322bbd8c599a6af186a1603b3355e59a5fb1baa139f8f4c3c9a1b3e3d57" }, + "@std/fmt@0.223.0": { + "integrity": "6deb37794127dfc7d7bded2586b9fc6f5d50e62a8134846608baf71ffc1a5208" + }, + "@std/fmt@1.0.2": { + "integrity": "87e9dfcdd3ca7c066e0c3c657c1f987c82888eb8103a3a3baa62684ffeb0f7a7" + }, + "@std/fs@0.223.0": { + "integrity": "3b4b0550b2c524cbaaa5a9170c90e96cbb7354e837ad1bdaf15fc9df1ae9c31c" + }, + "@std/fs@0.229.3": { + "integrity": "783bca21f24da92e04c3893c9e79653227ab016c48e96b3078377ebd5222e6eb", + "dependencies": [ + "jsr:@std/path@1.0.0-rc.1" + ] + }, "@std/fs@1.0.4": { "integrity": "2907d32d8d1d9e540588fd5fe0ec21ee638134bd51df327ad4e443aaef07123c", "dependencies": [ @@ -40,12 +108,37 @@ "@std/internal@1.0.4": { "integrity": "62e8e4911527e5e4f307741a795c0b0a9e6958d0b3790716ae71ce085f755422" }, + "@std/io@0.223.0": { + "integrity": "2d8c3c2ab3a515619b90da2c6ff5ea7b75a94383259ef4d02116b228393f84f1", + "dependencies": [ + "jsr:@std/assert@^0.223.0", + "jsr:@std/bytes@^0.223.0" + ] + }, "@std/io@0.224.9": { "integrity": "4414664b6926f665102e73c969cfda06d2c4c59bd5d0c603fd4f1b1c840d6ee3", "dependencies": [ "jsr:@std/bytes@^1.0.2" ] }, + "@std/jsonc@1.0.1": { + "integrity": "6b36956e2a7cbb08ca5ad7fbec72e661e6217c202f348496ea88747636710dda" + }, + "@std/path@0.223.0": { + "integrity": "593963402d7e6597f5a6e620931661053572c982fc014000459edc1f93cc3989", + "dependencies": [ + "jsr:@std/assert@^0.223.0" + ] + }, + "@std/path@0.225.2": { + "integrity": "0f2db41d36b50ef048dcb0399aac720a5348638dd3cb5bf80685bf2a745aa506", + "dependencies": [ + "jsr:@std/assert@^0.226.0" + ] + }, + "@std/path@1.0.0-rc.1": { + "integrity": "b8c00ae2f19106a6bb7cbf1ab9be52aa70de1605daeb2dbdc4f87a7cbaf10ff6" + }, "@std/path@1.0.6": { "integrity": "ab2c55f902b380cf28e0eec501b4906e4c1960d13f00e11cfbcd21de15f18fed" }, @@ -57,6 +150,19 @@ "jsr:@std/internal@^1.0.1", "jsr:@std/path@^1.0.2" ] + }, + "@ts-morph/bootstrap@0.24.0": { + "integrity": "a826a2ef7fa8a7c3f1042df2c034d20744d94da2ee32bf29275bcd4dffd3c060", + "dependencies": [ + "jsr:@ts-morph/common@^0.24.0" + ] + }, + "@ts-morph/common@0.24.0": { + "integrity": "12b625b8e562446ba658cdbe9ad77774b4bd96b992ae8bd34c60dbf24d06c1f3", + "dependencies": [ + "jsr:@std/fs@^0.229.3", + "jsr:@std/path@^0.225.2" + ] } }, "npm": {