diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index f509ea9..90406fd 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -26,6 +26,12 @@ jobs: run: deno task format - name: Check types run: deno task check + - name: Regenerate V2 + uses: nickcharlton/diff-check@main + with: + command: deno task generate-v2-client + - name: V2 Smoke Test + run: deno task test:single src/v2/tests/smoke_test.ts - name: Test run: deno task test:coverage - name: Archive code coverage results diff --git a/deno.jsonc b/deno.jsonc index 0b6133a..50bcb10 100644 --- a/deno.jsonc +++ b/deno.jsonc @@ -25,10 +25,10 @@ "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.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.13.12 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", + "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 cb775ff..9dde431 100644 --- a/deno.lock +++ b/deno.lock @@ -9,10 +9,8 @@ "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/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/data-structures@^1.0.4": "jsr:@std/data-structures@1.0.4", + "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", @@ -20,10 +18,9 @@ "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/fs@^1.0.4": "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": "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", @@ -33,14 +30,16 @@ "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.3", + "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.13.12": "npm:@openapitools/openapi-generator-cli@2.13.12_@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:@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:typescript@^5.4.5": "npm:typescript@5.6.2" }, "jsr": { @@ -73,26 +72,17 @@ "@std/assert@0.226.0": { "integrity": "0dfb5f7c7723c18cec118e080fec76ce15b4c31154b15ad2bd74822603ef75b3" }, - "@std/assert@1.0.2": { - "integrity": "ccacec332958126deaceb5c63ff8b4eaf9f5ed0eac9feccf124110435e59e49c", - "dependencies": [ - "jsr:@std/internal@^1.0.1" - ] - }, "@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/data-structures@1.0.4": { - "integrity": "fa0e20c11eb9ba673417450915c750a0001405a784e2a4e0c3725031681684a0" + "@std/bytes@1.0.2": { + "integrity": "fbdee322bbd8c599a6af186a1603b3355e59a5fb1baa139f8f4c3c9a1b3e3d57" }, "@std/fmt@0.223.0": { "integrity": "6deb37794127dfc7d7bded2586b9fc6f5d50e62a8134846608baf71ffc1a5208" @@ -115,9 +105,6 @@ "jsr:@std/path@^1.0.6" ] }, - "@std/internal@1.0.1": { - "integrity": "6f8c7544d06a11dd256c8d6ba54b11ed870aac6c5aeafff499892662c57673e6" - }, "@std/internal@1.0.4": { "integrity": "62e8e4911527e5e4f307741a795c0b0a9e6958d0b3790716ae71ce085f755422" }, @@ -128,6 +115,12 @@ "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" }, @@ -149,15 +142,13 @@ "@std/path@1.0.6": { "integrity": "ab2c55f902b380cf28e0eec501b4906e4c1960d13f00e11cfbcd21de15f18fed" }, - "@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" + "jsr:@std/assert@^1.0.2", + "jsr:@std/fs@^1.0.1", + "jsr:@std/internal@^1.0.1", + "jsr:@std/path@^1.0.2" ] }, "@ts-morph/bootstrap@0.24.0": { @@ -225,8 +216,8 @@ "node-fetch": "node-fetch@2.7.0" } }, - "@openapitools/openapi-generator-cli@2.13.12_@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-ieYnbFiSYAEXmmLea+BLh50kMCnUxUoMfElKvFNFPkK8xDCFIzdsa5OVfR/gUKJRuWz/znbEF+zIY3rXlBT+3Q==", + "@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", @@ -239,7 +230,7 @@ "concurrently": "concurrently@6.5.1", "console.table": "console.table@0.10.0", "fs-extra": "fs-extra@10.1.0", - "glob": "glob@7.2.3", + "glob": "glob@9.3.5", "https-proxy-agent": "https-proxy-agent@7.0.5", "inquirer": "inquirer@8.2.6", "lodash": "lodash@4.17.21", @@ -248,14 +239,71 @@ "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": { @@ -278,14 +326,26 @@ "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.7": { + "integrity": "sha512-D/K0J5Zm6KvaMTnsWrBQZWLzKN9GxUFZEa0mx2qeEHXDeTugCoplWehy8y36dj5vuSjhe1u/Dol8cZ8lzzmDew==", + "dependencies": { + "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.8", + "follow-redirects": "follow-redirects@1.15.9", "form-data": "form-data@4.0.0", "proxy-from-env": "proxy-from-env@1.1.0" } @@ -306,11 +366,10 @@ "readable-stream": "readable-stream@3.6.2" } }, - "brace-expansion@1.1.11": { - "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==", + "brace-expansion@2.0.1": { + "integrity": "sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA==", "dependencies": { - "balanced-match": "balanced-match@1.0.2", - "concat-map": "concat-map@0.0.1" + "balanced-match": "balanced-match@1.0.2" } }, "buffer@5.7.1": { @@ -320,6 +379,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": { @@ -327,6 +390,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": {} @@ -373,6 +444,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": {} @@ -381,10 +456,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": { @@ -434,6 +505,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": { @@ -444,6 +521,10 @@ "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==", "dependencies": {} }, + "entities@4.5.0": { + "integrity": "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==", + "dependencies": {} + }, "escalade@3.2.0": { "integrity": "sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==", "dependencies": {} @@ -460,6 +541,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": {} @@ -486,8 +571,8 @@ "escape-string-regexp": "escape-string-regexp@1.0.5" } }, - "follow-redirects@1.15.8": { - "integrity": "sha512-xgrmBhBToVKay1q2Tao5LI26B83UhrB/vM1avwVSDzt8rx3rO6AizBAaF46EgksTVr+rFTQaqZZ9MVBfUe4nig==", + "follow-redirects@1.15.9": { + "integrity": "sha512-gew4GsXizNgdoRyqmyfMHyAmXsZDk6mHkSxZFCzW9gwlbtOW44CDtYavM+y+72qD/Vq2l550kMF52DT8fOLJqQ==", "dependencies": {} }, "form-data@4.0.0": { @@ -518,15 +603,13 @@ "integrity": "sha512-lkX1HJXwyMcprw/5YUZc2s7DrpAiHB21/V+E1rHUrVNokkvB6bqMzT0VfV6/86ZNabt1k14YOIaT7nDvOX3Iiw==", "dependencies": {} }, - "glob@7.2.3": { - "integrity": "sha512-nFR0zLpU2YCaRxwoCJvL6UvCH2JFyFVIvwTLsIf21AuHlMskA1hhTdk+LlYJtOlYt9v6dvszD2BGRqBL+iQK9Q==", + "glob@9.3.5": { + "integrity": "sha512-e1LleDykUz2Iu+MTYdkSsuWX8lvAjAcs0Xef0lNIu0S2wOAzuTxCJtcd9S3cijlwYF18EsU3rzb8jPVobxDh9Q==", "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" + "minimatch": "minimatch@8.0.4", + "minipass": "minipass@4.2.8", + "path-scurry": "path-scurry@1.11.1" } }, "graceful-fs@4.2.11": { @@ -537,6 +620,32 @@ "integrity": "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==", "dependencies": {} }, + "hast-util-to-html@9.0.3": { + "integrity": "sha512-M17uBDzMJ9RPCqLMO92gNNUDuBSq10a25SDBI08iCCxmorf4Yy6sYHK57n9WAbRAAaU+DuR4W6GN9K4DFZesYg==", + "dependencies": { + "@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": { @@ -554,13 +663,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": {} @@ -585,6 +687,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": {} @@ -612,6 +718,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": {} @@ -623,6 +735,70 @@ "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": {} + }, + "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": { "integrity": "sha512-sPU4uV7dYlvtWJxwwxHD0PuihVNiE7TyAbQ5SWxDCB9mUYvOgroQOwYQQOKPJ8CIbE+1ETVlOoK1UC2nU3gYvg==", "dependencies": {} @@ -637,12 +813,26 @@ "integrity": "sha512-OqbOk5oEQeAZ8WXWydlu9HJjz9WVdEIvamMCcXmuqUYjTknH/sqsWvhQ3vgwKFRR1HpjvNBKQ37nbJgYzGqGcg==", "dependencies": {} }, - "minimatch@3.1.2": { - "integrity": "sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw==", + "minimatch@8.0.4": { + "integrity": "sha512-W0Wvr9HyFXZRGIDgCicunpQ299OKXs9RgZfaukz4qAW/pJhcpUfupc9c+OObPOFueNy8VSrZgEmDtk6Kh4WzDA==", "dependencies": { - "brace-expansion": "brace-expansion@1.1.11" + "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.3": { "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==", "dependencies": {} @@ -661,18 +851,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": { @@ -691,18 +881,29 @@ "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": { + "lru-cache": "lru-cache@10.4.3", + "minipass": "minipass@7.1.2" + } }, "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": { @@ -719,6 +920,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": {} @@ -758,10 +963,25 @@ "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==", "dependencies": {} }, + "shiki@1.21.0": { + "integrity": "sha512-apCH5BoWTrmHDPGgg3RF8+HAAbEL/CdbYr8rMw7eIrdhCkZHdVGat5mMNlRtd1erNG01VPMIKHNQ0Pj2HMAiog==", + "dependencies": { + "@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": {} }, + "space-separated-tokens@2.0.2": { + "integrity": "sha512-PEGlAwrG8yXGXRjW32fGbg66JAlOAwbObuqVoJpv/mRgoWDQfgH1wDPvtzWyUSNAXBGSk8h755YDbbcEy3SH2Q==", + "dependencies": {} + }, "spawn-command@0.0.2": { "integrity": "sha512-zC8zGoGkmc8J9ndvml8Xksr1Amk9qBujgbF0JAIWO7kXr43w0h/0GJNM/Vustixu+YE8N/MTrQ7N31FvHUACxQ==", "dependencies": {} @@ -780,6 +1000,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": { @@ -816,6 +1043,10 @@ "integrity": "sha512-L0Orpi8qGpRG//Nd+H90vFB+3iHnue1zSSGmNOOCh1GLJ7rUKVwV2HvijphGQS2UmhUZewS9VgvxYIdgr+fG1A==", "dependencies": {} }, + "trim-lines@3.0.1": { + "integrity": "sha512-kRj8B+YHZCc9kQYdWfJB2/oUl9rA99qbowYYBtr4ui4mZyAQ2JpvVBd/6U2YloATfqBhBTSMhTpgBHtU0Mf3Rg==", + "dependencies": {} + }, "tslib@1.14.1": { "integrity": "sha512-Xni35NKzjgMrwevysHTCArtLDpPvye8zV/0E4EyYn43P7/7qvQwPh9BGkHewbMulVntbigmcT7rdX3BNo9wRJg==", "dependencies": {} @@ -828,16 +1059,64 @@ "integrity": "sha512-t0rzBq87m3fVcduHDUFhKmyyX+9eo6WQjZvf51Ea/M0Q7+T374Jp1aUiyUl0GKxp8M/OETVHSDvmkyPgvX+X2w==", "dependencies": {} }, + "typedoc@0.26.7_typescript@5.6.2": { + "integrity": "sha512-gUeI/Wk99vjXXMi8kanwzyhmeFEGv1LTdTQsiyIsmSYsBebvFxhbcyAx7Zjo4cMbpLGxM4Uz3jVIjksu/I2v6Q==", + "dependencies": { + "lunr": "lunr@2.3.9", + "markdown-it": "markdown-it@14.1.0", + "minimatch": "minimatch@9.0.5", + "shiki": "shiki@1.21.0", + "typescript": "typescript@5.6.2", + "yaml": "yaml@2.5.1" + } + }, "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": {} @@ -846,6 +1125,20 @@ "integrity": "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==", "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" + } + }, + "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==", "dependencies": { @@ -879,14 +1172,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": {} @@ -902,10 +1195,16 @@ "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", diff --git a/openapi/2024-09-05.json b/openapi/2024-10-08.json similarity index 70% rename from openapi/2024-09-05.json rename to openapi/2024-10-08.json index 70b2c29..b6aeb5f 100644 --- a/openapi/2024-09-05.json +++ b/openapi/2024-10-08.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,1282 +1642,1071 @@ } }, "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" + "BadRequestError": { + "examples": [ + { + "code": "bad-request", + "message": "🚨 Error! Sound the alarm! 🚨" + } + ], + "properties": { + "code": { + "description": "Error code", + "const": "bad-request", + "type": "string" }, - "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" - } - ] + "message": { + "description": "Error message", + "type": "string" + } }, + "required": [ + "code", + "message" + ], + "type": "object" + }, + "ConflictError": { + "examples": [ + { + "code": "conflict", + "message": "🚨 Error! Sound the alarm! 🚨" + } + ], "properties": { - "data": { - "description": "A page of ListWithType results", - "items": { - "$ref": "#/components/schemas/ListWithType" - }, - "type": "array" + "code": { + "description": "Error code", + "const": "conflict", + "type": "string" }, - "pagination": { - "$ref": "#/components/schemas/Pagination" + "message": { + "description": "Error message", + "type": "string" } }, "required": [ - "data", - "pagination" + "code", + "message" ], "type": "object" }, - "ListWithType": { - "description": "ListWithType model", - "example": { - "name": "All companies", - "creatorId": 1, - "isPublic": false, - "id": 1, - "ownerId": 1, - "type": "company" - }, + "MethodNotAllowedError": { + "examples": [ + { + "code": "method-not-allowed", + "message": "🚨 Error! Sound the alarm! 🚨" + } + ], "properties": { - "id": { - "description": "The unique identifier for the list", - "example": 1, - "format": "int64", - "type": "integer" - }, - "name": { - "description": "The name of the list", - "example": "All companies", + "code": { + "description": "Error code", + "const": "method-not-allowed", "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" - ], - "example": "company", + "message": { + "description": "Error message", "type": "string" } }, "required": [ - "creatorId", - "id", - "isPublic", - "name", - "ownerId", - "type" + "code", + "message" ], "type": "object" }, - "Pagination": { - "example": { - "prevUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgYmVmb3JlOjo6Nw", - "nextUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgIGFmdGVyOjo6NA" - }, + "NotAcceptableError": { + "examples": [ + { + "code": "not-acceptable", + "message": "🚨 Error! Sound the alarm! 🚨" + } + ], "properties": { - "prevUrl": { - "description": "URL for the previous page", - "example": "https://api.affinity.co/v2/foo?cursor=ICAgICAgYmVmb3JlOjo6Nw", - "format": "url", - "type": "string", - "nullable": true + "code": { + "description": "Error code", + "const": "not-acceptable", + "type": "string" }, - "nextUrl": { - "description": "URL for the next page", - "example": "https://api.affinity.co/v2/foo?cursor=ICAgICAgIGFmdGVyOjo6NA", - "format": "url", - "type": "string", - "nullable": true + "message": { + "description": "Error message", + "type": "string" } }, + "required": [ + "code", + "message" + ], "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" + "NotImplementedError": { + "examples": [ + { + "code": "not-implemented", + "message": "🚨 Error! Sound the alarm! 🚨" + } + ], + "properties": { + "code": { + "description": "Error code", + "const": "not-implemented", + "type": "string" }, - "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" - } - ] + "message": { + "description": "Error message", + "type": "string" + } }, + "required": [ + "code", + "message" + ], + "type": "object" + }, + "RateLimitError": { + "examples": [ + { + "code": "rate-limit", + "message": "🚨 Error! Sound the alarm! 🚨" + } + ], "properties": { - "data": { - "description": "A page of Person results", - "items": { - "$ref": "#/components/schemas/Person" - }, - "type": "array" + "code": { + "description": "Error code", + "const": "rate-limit", + "type": "string" }, - "pagination": { - "$ref": "#/components/schemas/Pagination" + "message": { + "description": "Error message", + "type": "string" } }, "required": [ - "data", - "pagination" + "code", + "message" ], "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" - }, + "ServerError": { + "examples": [ + { + "code": "server", + "message": "🚨 Error! Sound the alarm! 🚨" + } + ], "properties": { - "id": { - "description": "The persons's unique identifier", - "example": 1, - "format": "int64", - "type": "integer" - }, - "firstName": { - "description": "The person's first name", - "example": "Jane", + "code": { + "description": "Error code", + "const": "server", "type": "string" }, - "lastName": { - "description": "The person's last name", - "example": "Doe", - "type": "string", - "nullable": true + "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" }, - "primaryEmailAddress": { - "description": "The person's primary email address", - "example": "jane.doe@acme.co", - "format": "email", - "type": "string", - "nullable": true + "message": { + "description": "Error message", + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "type": "object" + }, + "UnsupportedMediaTypeError": { + "examples": [ + { + "code": "unsupported-media-type", + "message": "🚨 Error! Sound the alarm! 🚨" + } + ], + "properties": { + "code": { + "description": "Error code", + "const": "unsupported-media-type", + "type": "string" }, - "emailAddresses": { - "description": "All of the person's email addresses", - "example": [ - "jane.doe@acme.co", - "janedoe@gmail.com" + "message": { + "description": "Error message", + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "type": "object" + }, + "Tenant": { + "examples": [ + { + "name": "Contoso Ltd.", + "subdomain": "contoso", + "id": 1 + } + ], + "properties": { + "id": { + "description": "The tenant's unique identifier", + "examples": [ + 1 ], - "items": { - "format": "email", - "type": "string" - }, - "type": "array" + "format": "int64", + "type": "integer" }, - "type": { - "description": "The person's type", - "enum": [ - "internal", - "external" + "name": { + "description": "The name of the tenant", + "examples": [ + "Contoso Ltd." ], - "example": "internal", "type": "string" }, - "fields": { - "description": "The fields associated with the person", - "items": { - "$ref": "#/components/schemas/Field" - }, - "type": "array" + "subdomain": { + "description": "The tenant's subdomain under affinity.co", + "examples": [ + "contoso" + ], + "format": "hostname", + "type": "string" } }, "required": [ - "emailAddresses", - "firstName", "id", - "lastName", - "primaryEmailAddress", - "type" + "name", + "subdomain" ], "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" + "User": { + "examples": [ + { + "firstName": "John", + "lastName": "Smith", + "emailAddress": "john.smith@contoso.com", + "id": 1 } - }, + ], "properties": { "id": { - "description": "The field's unique identifier", - "example": "affinity-data-location", - "type": "string" - }, - "name": { - "description": "The field's name", - "example": "Location", - "type": "string" + "description": "The user's unique identifier", + "examples": [ + 1 + ], + "format": "int64", + "type": "integer" }, - "type": { - "description": "The field's type", - "enum": [ - "enriched", - "global", - "list", - "relationship-intelligence" + "firstName": { + "description": "The user's first name", + "examples": [ + "John" ], - "example": "enriched", "type": "string" }, - "enrichmentSource": { - "description": "The source of the data in this Field (if it is enriched)", - "enum": [ - "affinity-data", - "dealroom", - null + "lastName": { + "description": "The user's last name", + "examples": [ + "Smith" ], - "example": "affinity-data", - "type": "string", - "nullable": true + "type": [ + "string", + "null" + ] }, - "value": { - "$ref": "#/components/schemas/FieldValue" + "emailAddress": { + "description": "The user's email address", + "examples": [ + "john.smith@contoso.com" + ], + "format": "email", + "type": "string" } }, "required": [ - "enrichmentSource", + "emailAddress", + "firstName", "id", - "name", - "type", - "value" + "lastName" ], "type": "object" }, - "FieldValue": { - "example": { - "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": { "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" + "description": "The type of grant used to authenticate", + "const": "api-key", + "examples": [ + "api-key" + ], + "type": "string" + }, + "scopes": { + "description": "The scopes available to the current grant", + "examples": [ + [ + "api" + ] + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "createdAt": { + "description": "When the grant was created", + "examples": [ + "2023-01-01T00:00:00Z" ], - "example": "location", + "format": "date-time", "type": "string" } }, "required": [ + "createdAt", + "scopes", "type" ], - "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" - }, + "type": "object" + }, + "WhoAmI": { + "description": "WhoAmI model", + "examples": [ { - "$ref": "#/components/schemas/CompanyValue" + "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": { + "tenant": { + "$ref": "#/components/schemas/Tenant" }, - { - "$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" + "user": { + "$ref": "#/components/schemas/User" }, + "grant": { + "$ref": "#/components/schemas/Grant" + } + }, + "required": [ + "grant", + "tenant", + "user" + ], + "type": "object" + }, + "AuthenticationError": { + "examples": [ { - "$ref": "#/components/schemas/DropdownValue" + "code": "authentication", + "message": "🚨 Error! Sound the alarm! 🚨" + } + ], + "properties": { + "code": { + "description": "Error code", + "const": "authentication", + "type": "string" }, + "message": { + "description": "Error message", + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "type": "object" + }, + "AuthenticationErrors": { + "description": "AuthenticationErrors model", + "examples": [ { - "$ref": "#/components/schemas/DropdownsValue" - }, + "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" + } + }, + "required": [ + "errors" + ], + "type": "object" + }, + "NotFoundError": { + "examples": [ { - "$ref": "#/components/schemas/FormulaValue" + "code": "not-found", + "message": "🚨 Error! Sound the alarm! 🚨" + } + ], + "properties": { + "code": { + "description": "Error code", + "const": "not-found", + "type": "string" }, - { - "$ref": "#/components/schemas/InteractionValue" + "message": { + "description": "Error message", + "type": "string" } - ] + }, + "required": [ + "code", + "message" + ], + "type": "object" }, - "Location": { - "example": { - "continent": "North America", - "country": "United States", - "streetAddress": "170 Columbus Ave", - "city": "San Francisco", - "state": "California" + "NotFoundErrors": { + "description": "NotFoundErrors model", + "examples": [ + { + "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" + }, + "type": "array" + } }, + "required": [ + "errors" + ], + "type": "object" + }, + "CompanyData": { "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 + "id": { + "description": "The company's unique identifier", + "examples": [ + 1 + ], + "format": "int64", + "type": "integer" }, - "country": { - "description": "Country", - "example": "United States", - "type": "string", - "nullable": true + "name": { + "description": "The company's name", + "examples": [ + "Acme" + ], + "type": "string" }, - "continent": { - "description": "Continent", - "example": "North America", - "type": "string", - "nullable": true + "domain": { + "description": "The company's primary domain", + "examples": [ + "acme.co" + ], + "format": "hostname", + "type": [ + "string", + "null" + ] } }, "required": [ - "city", - "continent", - "country", - "state", - "streetAddress" + "domain", + "id", + "name" ], "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 - } - ] - }, + "CompaniesValue": { + "title": "CompaniesValue", "properties": { + "type": { + "description": "The type of value", + "const": "company-multi", + "type": "string" + }, "data": { - "description": "A page of Opportunity results", + "description": "The values for many companies", "items": { - "$ref": "#/components/schemas/Opportunity" + "$ref": "#/components/schemas/CompanyData" }, - "type": "array" + "type": [ + "array", + "null" + ] + } + }, + "required": [ + "data", + "type" + ], + "type": "object" + }, + "CompanyValue": { + "title": "CompanyValue", + "properties": { + "type": { + "description": "The type of value", + "const": "company", + "type": "string" }, - "pagination": { - "$ref": "#/components/schemas/Pagination" + "data": { + "oneOf": [ + { + "$ref": "#/components/schemas/CompanyData" + }, + { + "type": "null" + } + ] } }, "required": [ "data", - "pagination" + "type" ], "type": "object" }, - "Opportunity": { - "description": "Opportunity model", - "example": { - "listId": 1, - "name": "Acme Upsell $10k", - "id": 1 + "DateValue": { + "title": "DateValue", + "properties": { + "type": { + "description": "The type of value", + "const": "datetime", + "type": "string" + }, + "data": { + "description": "The value for a date", + "format": "date-time", + "type": [ + "string", + "null" + ] + } }, + "required": [ + "data", + "type" + ], + "type": "object" + }, + "Dropdown": { "properties": { - "id": { - "description": "The unique identifier for the opportunity", - "example": 1, + "dropdownOptionId": { + "description": "Dropdown item's unique identifier", + "examples": [ + 1 + ], "format": "int64", "type": "integer" }, - "name": { - "description": "The name of the opportunity", - "example": "Acme Upsell $10k", + "text": { + "description": "Dropdown item text", + "examples": [ + "first" + ], "type": "string" - }, - "listId": { - "description": "The ID of the list that the opportunity belongs to", - "example": 1, - "format": "int64", - "type": "integer" } }, "required": [ - "id", - "listId", - "name" + "dropdownOptionId", + "text" ], "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" + "DropdownValue": { + "title": "DropdownValue", + "properties": { + "type": { + "description": "The type of value", + "const": "dropdown", + "type": "string" }, - "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" - } - } - ] + "data": { + "oneOf": [ + { + "$ref": "#/components/schemas/Dropdown" + }, + { + "type": "null" } - } - ] + ] + } }, + "required": [ + "data", + "type" + ], + "type": "object" + }, + "DropdownsValue": { + "title": "DropdownsValue", "properties": { + "type": { + "description": "The type of value", + "const": "dropdown-multi", + "type": "string" + }, "data": { - "description": "A page of ListEntryWithEntity results", + "description": "The value for many dropdown items", "items": { - "$ref": "#/components/schemas/ListEntryWithEntity" + "$ref": "#/components/schemas/Dropdown" }, - "type": "array", - "nullable": true - }, - "pagination": { - "$ref": "#/components/schemas/Pagination" + "type": [ + "array", + "null" + ] } }, "required": [ "data", - "pagination" + "type" ], "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": [ - { - "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" - } - } + "FloatValue": { + "title": "FloatValue", + "properties": { + "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 entity type for this list entry", - "enum": [ - "company", - "opportunity", - "person" - ], - "example": "company", + "description": "The type of value", + "const": "number-multi", "type": "string" + }, + "data": { + "description": "The value for many numbers", + "items": { + "type": "number" + }, + "type": [ + "array", + "null" + ] } }, "required": [ + "data", "type" ], - "type": "object", - "discriminator": { - "propertyName": "type", - "mapping": { - "company": "#/components/schemas/CompanyListEntry", - "opportunity": "#/components/schemas/OpportunityListEntry", - "person": "#/components/schemas/PersonListEntry" + "type": "object" + }, + "FormulaNumber": { + "properties": { + "calculatedValue": { + "description": "Calculated value", + "type": [ + "number", + "null" + ] } }, - "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" - } - } - ] - }, + "FormulaValue": { + "title": "FormulaValue", "properties": { - "id": { - "description": "The company's unique identifier", - "example": 1, - "format": "int64", - "type": "integer" - }, - "name": { - "description": "The company's name", - "example": "Acme", - "type": "string" - }, - "domain": { - "description": "The company's primary domain", - "example": "acme.co", - "format": "hostname", + "type": { + "description": "The type of value", + "const": "formula-number", "type": "string" }, - "domains": { - "description": "All of the company's domains", - "example": [ - "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" + "data": { + "oneOf": [ + { + "$ref": "#/components/schemas/FormulaNumber" + }, + { + "type": "null" + } + ] } }, "required": [ - "domain", - "domains", - "id", - "isGlobal", - "name" + "data", + "type" ], "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" - } - ] - }, + "PersonData": { "properties": { - "data": { - "description": "A page of SavedView results", - "items": { - "$ref": "#/components/schemas/SavedView" - }, - "type": "array" + "id": { + "description": "The persons's unique identifier", + "examples": [ + 1 + ], + "format": "int64", + "type": "integer" + }, + "firstName": { + "description": "The person's first name", + "examples": [ + "Jane" + ], + "type": [ + "string", + "null" + ] + }, + "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" + ] }, - "pagination": { - "$ref": "#/components/schemas/Pagination" + "type": { + "description": "The person's type", + "enum": [ + "internal", + "external", + "collaborator" + ], + "examples": [ + "internal" + ], + "type": "string" } }, "required": [ - "data", - "pagination" + "firstName", + "id", + "lastName", + "primaryEmailAddress", + "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" - }, + "ChatMessage": { "properties": { + "type": { + "description": "The type of interaction", + "const": "chat-message", + "examples": [ + "chat-message" + ], + "type": "string" + }, "id": { - "description": "The saved view's unique identifier", - "example": 28, + "description": "The chat message's unique identifier", + "examples": [ + 1 + ], "format": "int64", "type": "integer" }, - "name": { - "description": "The saved view's name", - "example": "my interesting companies", - "type": "string" - }, - "type": { - "description": "The type for this saved view", + "direction": { + "description": "The direction of the chat message", "enum": [ - "sheet", - "board", - "dashboard" + "received", + "sent" + ], + "examples": [ + "outbound" ], - "example": "sheet", "type": "string" }, - "createdAt": { - "description": "The date that the saved view was created", - "example": "2023-01-01 00:00:00.000000000 Z", + "sentAt": { + "description": "The time the chat message was sent", + "examples": [ + "2023-01-01T00:00:00Z" + ], "format": "date-time", "type": "string" + }, + "manualCreator": { + "$ref": "#/components/schemas/PersonData" + }, + "participants": { + "description": "The participants of the chat", + "items": { + "$ref": "#/components/schemas/PersonData" + }, + "type": "array" } }, "required": [ - "createdAt", + "direction", "id", - "name", + "manualCreator", + "participants", + "sentAt", "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" - }, - "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" - } - } - ] - } - ] - }, + "Attendee": { "properties": { - "data": { - "description": "A page of Company results", - "items": { - "$ref": "#/components/schemas/Company" - }, - "type": "array" + "emailAddress": { + "description": "The email addresses of the attendee", + "examples": [ + "john.smith@contoso.com" + ], + "format": "email", + "type": [ + "string", + "null" + ] }, - "pagination": { - "$ref": "#/components/schemas/Pagination" + "person": { + "oneOf": [ + { + "$ref": "#/components/schemas/PersonData" + }, + { + "type": "null" + } + ] } }, "required": [ - "data", - "pagination" + "emailAddress", + "person" ], "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" - } - ] - }, + "Email": { "properties": { - "data": { - "description": "A page of FieldMetadata results", + "type": { + "description": "The type of interaction", + "const": "email", + "examples": [ + "email" + ], + "type": "string" + }, + "id": { + "description": "The email's unique identifier", + "examples": [ + 1 + ], + "format": "int64", + "type": "integer" + }, + "subject": { + "description": "The subject of the email", + "examples": [ + "Acme Upsell $10k" + ], + "type": [ + "string", + "null" + ] + }, + "sentAt": { + "description": "The time the email was sent", + "examples": [ + "2023-01-01T00:00:00Z" + ], + "format": "date-time", + "type": "string" + }, + "from": { + "$ref": "#/components/schemas/Attendee" + }, + "to": { + "description": "The recipients of the email", "items": { - "$ref": "#/components/schemas/FieldMetadata" + "$ref": "#/components/schemas/Attendee" }, "type": "array" }, - "pagination": { - "$ref": "#/components/schemas/Pagination" + "cc": { + "description": "The cc recipients of the email", + "items": { + "$ref": "#/components/schemas/Attendee" + }, + "type": "array" } }, "required": [ - "data", - "pagination" + "cc", + "from", + "id", + "sentAt", + "subject", + "to", + "type" ], "type": "object" }, - "FieldMetadata": { - "example": { - "enrichmentSource": "affinity-data", - "valueType": "location", - "name": "Location", - "id": "affinity-data-location", - "type": "enriched" - }, + "Meeting": { "properties": { - "id": { - "description": "The field's unique identifier", - "example": "affinity-data-location", + "type": { + "description": "The type of interaction", + "const": "meeting", + "examples": [ + "meeting" + ], "type": "string" }, - "name": { - "description": "The field's name", - "example": "Location", - "type": "string" + "id": { + "description": "The meeting's unique identifier", + "examples": [ + 1 + ], + "format": "int64", + "type": "integer" }, - "type": { - "description": "The field's type", - "enum": [ - "enriched", - "global", - "list", - "relationship-intelligence" + "title": { + "description": "The meeting's title", + "examples": [ + "Acme Upsell $10k" ], - "example": "enriched", - "type": "string" + "type": [ + "string", + "null" + ] }, - "enrichmentSource": { - "description": "The source of the data in this Field (if it is enriched)", - "enum": [ - "affinity-data", - "dealroom", - null + "allDay": { + "description": "Whether the meeting is an all-day event", + "examples": [ + false ], - "example": "affinity-data", - "type": "string", - "nullable": true + "type": "boolean" }, - "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" + "startTime": { + "description": "The meeting start time", + "examples": [ + "2023-02-03T04:00:00Z" ], - "example": "location", + "format": "date-time", "type": "string" + }, + "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/Attendee" + }, + "type": "array" } }, "required": [ - "enrichmentSource", + "allDay", + "attendees", + "endTime", "id", - "name", - "type", - "valueType" + "startTime", + "title", + "type" ], "type": "object" }, @@ -2925,29 +2714,30 @@ "properties": { "type": { "description": "The type of interaction", - "enum": [ + "const": "call", + "examples": [ "call" ], - "example": "call", "type": "string" }, "id": { "description": "The phon_call's unique identifier", - "example": 1, + "examples": [ + 1 + ], "format": "int64", "type": "integer" }, "startTime": { "description": "The call start time", - "example": "2023-02-03 04:00:00.000000000 Z", + "examples": [ + "2023-02-03T04:00:00Z" + ], "format": "date-time", "type": "string" }, "attendees": { "description": "People attending the call", - "example": [ - "Affinity::ExternalAPIV2::Examples::Attendee" - ], "items": { "$ref": "#/components/schemas/Attendee" }, @@ -2962,19 +2752,62 @@ ], "type": "object" }, - "Attendee": { + "Interaction": { "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 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" }, - "person": { + { + "$ref": "#/components/schemas/Email" + }, + { + "$ref": "#/components/schemas/Meeting" + }, + { + "$ref": "#/components/schemas/PhoneCall" + } + ] + }, + "InteractionValue": { + "title": "InteractionValue", + "properties": { + "type": { + "description": "The type of value", + "const": "interaction", + "type": "string" + }, + "data": { "oneOf": [ { - "$ref": "#/components/schemas/PersonData" + "$ref": "#/components/schemas/Interaction" }, { "type": "null" @@ -2983,249 +2816,342 @@ } }, "required": [ - "emailAddress", - "person" + "data", + "type" ], "type": "object" }, - "PersonData": { + "Location": { + "examples": [ + { + "continent": "North America", + "country": "United States", + "streetAddress": "170 Columbus Ave", + "city": "San Francisco", + "state": "California" + } + ], "properties": { - "id": { - "description": "The persons's unique identifier", - "example": 1, - "format": "int64", - "type": "integer" + "streetAddress": { + "description": "Street address", + "examples": [ + "170 Columbus Ave" + ], + "type": [ + "string", + "null" + ] }, - "firstName": { - "description": "The person's first name", - "example": "Jane", - "type": "string", - "nullable": true + "city": { + "description": "City", + "examples": [ + "San Francisco" + ], + "type": [ + "string", + "null" + ] }, - "lastName": { - "description": "The person's last name", - "example": "Doe", - "type": "string", - "nullable": true + "state": { + "description": "State", + "examples": [ + "California" + ], + "type": [ + "string", + "null" + ] }, - "primaryEmailAddress": { - "description": "The person's primary email address", - "example": "jane.doe@acme.co", - "format": "email", - "type": "string", - "nullable": true + "country": { + "description": "Country", + "examples": [ + "United States" + ], + "type": [ + "string", + "null" + ] }, - "type": { - "description": "The person's type", - "enum": [ - "internal", - "external", - "collaborator" + "continent": { + "description": "Continent", + "examples": [ + "North America" ], - "example": "internal", + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "city", + "continent", + "country", + "state", + "streetAddress" + ], + "type": "object" + }, + "LocationValue": { + "title": "LocationValue", + "properties": { + "type": { + "description": "The type of value", + "const": "location", "type": "string" + }, + "data": { + "oneOf": [ + { + "$ref": "#/components/schemas/Location" + }, + { + "type": "null" + } + ] } }, "required": [ - "firstName", - "id", - "lastName", - "primaryEmailAddress", + "data", + "type" + ], + "type": "object" + }, + "LocationsValue": { + "title": "LocationsValue", + "properties": { + "type": { + "description": "The type of value", + "const": "location-multi", + "type": "string" + }, + "data": { + "description": "The values for many locations", + "items": { + "$ref": "#/components/schemas/Location" + }, + "type": [ + "array", + "null" + ] + } + }, + "required": [ + "data", + "type" + ], + "type": "object" + }, + "PersonValue": { + "title": "PersonValue", + "properties": { + "type": { + "description": "The type of value", + "const": "person", + "type": "string" + }, + "data": { + "oneOf": [ + { + "$ref": "#/components/schemas/PersonData" + }, + { + "type": "null" + } + ] + } + }, + "required": [ + "data", "type" ], "type": "object" }, - "Meeting": { + "PersonsValue": { + "title": "PersonsValue", "properties": { "type": { - "description": "The type of interaction", - "enum": [ - "meeting" - ], - "example": "meeting", - "type": "string" - }, - "id": { - "description": "The meeting's unique identifier", - "example": 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" - }, - "startTime": { - "description": "The meeting start time", - "example": "2023-02-03 04:00:00.000000000 Z", - "format": "date-time", + "description": "The type of value", + "const": "person-multi", "type": "string" }, - "endTime": { - "description": "The meeting end time", - "example": "2023-02-03 05:00:00.000000000 Z", - "format": "date-time", - "type": "string", - "nullable": true - }, - "attendees": { - "description": "People attending the meeting", - "example": [ - "Affinity::ExternalAPIV2::Examples::Attendee" - ], + "data": { + "description": "The values for many persons", "items": { - "$ref": "#/components/schemas/Attendee" + "$ref": "#/components/schemas/PersonData" }, - "type": "array" + "type": [ + "array", + "null" + ] } }, "required": [ - "allDay", - "attendees", - "endTime", - "id", - "startTime", - "title", + "data", "type" ], "type": "object" }, - "Email": { + "RankedDropdown": { "properties": { - "type": { - "description": "The type of interaction", - "enum": [ - "email" + "dropdownOptionId": { + "description": "Dropdown item's unique identifier", + "examples": [ + 1 ], - "example": "email", - "type": "string" - }, - "id": { - "description": "The email's unique identifier", - "example": 1, "format": "int64", "type": "integer" }, - "subject": { - "description": "The subject of the email", - "example": "Acme Upsell $10k", - "type": "string", - "nullable": true - }, - "sentAt": { - "description": "The time the email was sent", - "example": "2023-01-01 00:00:00.000000000 Z", - "format": "date-time", + "text": { + "description": "Dropdown item text", + "examples": [ + "first" + ], "type": "string" }, - "from": { - "$ref": "#/components/schemas/Attendee" - }, - "to": { - "description": "The recipients of the email", - "example": [ - "Affinity::ExternalAPIV2::Examples::Attendee" + "rank": { + "description": "Dropdown item rank", + "examples": [ + 0 ], - "items": { - "$ref": "#/components/schemas/Attendee" - }, - "type": "array" + "format": "int64", + "type": "integer" }, - "cc": { - "description": "The cc recipients of the email", - "example": [ - "Affinity::ExternalAPIV2::Examples::Attendee" + "color": { + "description": "Dropdown item color", + "examples": [ + "white" ], - "items": { - "$ref": "#/components/schemas/Attendee" - }, - "type": "array" + "type": [ + "string", + "null" + ] } }, "required": [ - "cc", - "from", - "id", - "sentAt", - "subject", - "to", - "type" + "color", + "dropdownOptionId", + "rank", + "text" ], "type": "object" }, - "ChatMessage": { + "RankedDropdownValue": { + "title": "RankedDropdownValue", "properties": { "type": { - "description": "The type of interaction", - "enum": [ - "chat-message" - ], - "example": "chat-message", + "description": "The type of value", + "const": "ranked-dropdown", "type": "string" }, - "id": { - "description": "The chat message's unique identifier", - "example": 1, - "format": "int64", - "type": "integer" - }, - "direction": { - "description": "The direction of the chat message", + "data": { + "oneOf": [ + { + "$ref": "#/components/schemas/RankedDropdown" + }, + { + "type": "null" + } + ] + } + }, + "required": [ + "data", + "type" + ], + "type": "object" + }, + "TextValue": { + "title": "TextValue", + "properties": { + "type": { + "description": "The type of value", "enum": [ - "received", - "sent" + "filterable-text", + "text" + ], + "examples": [ + "filterable-text" ], - "example": "outbound", "type": "string" }, - "sentAt": { - "description": "The time the chat message was sent", - "example": "2023-01-01 00:00:00.000000000 Z", - "format": "date-time", + "data": { + "description": "The value for a string", + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "data", + "type" + ], + "type": "object" + }, + "TextsValue": { + "title": "TextsValue", + "properties": { + "type": { + "description": "The type of value", + "const": "filterable-text-multi", "type": "string" }, - "manualCreator": { - "$ref": "#/components/schemas/PersonData" - }, - "participants": { - "description": "The participants of the chat", - "example": [ - "Affinity::ExternalAPIV2::Examples::Person" - ], + "data": { + "description": "The value for many strings", "items": { - "$ref": "#/components/schemas/PersonData" + "type": "string" }, - "type": "array" + "type": [ + "array", + "null" + ] } }, "required": [ - "direction", - "id", - "manualCreator", - "participants", - "sentAt", + "data", "type" ], "type": "object" }, - "Interaction": { + "FieldValue": { + "examples": [ + { + "data": { + "continent": "North America", + "country": "United States", + "streetAddress": "170 Columbus Ave", + "city": "San Francisco", + "state": "California" + }, + "type": "location" + } + ], "properties": { "type": { - "description": "The type of interaction", + "description": "The type of value", "enum": [ - "call", - "email", - "meeting", - "chat-message" + "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" ], - "example": "meeting", "type": "string" } }, @@ -3236,605 +3162,750 @@ "discriminator": { "propertyName": "type", "mapping": { - "chat-message": "#/components/schemas/ChatMessage", - "email": "#/components/schemas/Email", - "meeting": "#/components/schemas/Meeting", - "call": "#/components/schemas/PhoneCall" + "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/ChatMessage" + "$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/Email" + "$ref": "#/components/schemas/LocationValue" }, { - "$ref": "#/components/schemas/Meeting" + "$ref": "#/components/schemas/LocationsValue" }, { - "$ref": "#/components/schemas/PhoneCall" + "$ref": "#/components/schemas/PersonValue" + }, + { + "$ref": "#/components/schemas/PersonsValue" + }, + { + "$ref": "#/components/schemas/RankedDropdownValue" + }, + { + "$ref": "#/components/schemas/TextValue" + }, + { + "$ref": "#/components/schemas/TextsValue" } ] }, - "InteractionValue": { - "properties": { - "type": { - "description": "The type of value", - "enum": [ - "interaction" - ], - "type": "string" - }, - "data": { - "oneOf": [ - { - "$ref": "#/components/schemas/Interaction" + "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": "null" - } - ] + "type": "location" + } } - }, - "required": [ - "data", - "type" ], - "type": "object" - }, - "FormulaNumber": { - "properties": { - "calculatedValue": { - "description": "Calculated value", - "type": "number", - "nullable": true - } - }, - "type": "object" - }, - "FormulaValue": { "properties": { - "type": { - "description": "The type of value", - "enum": [ - "formula-number" + "id": { + "description": "The field's unique identifier", + "examples": [ + "affinity-data-location" + ], + "type": "string" + }, + "name": { + "description": "The field's name", + "examples": [ + "Location" ], "type": "string" }, - "data": { - "oneOf": [ - { - "$ref": "#/components/schemas/FormulaNumber" - }, - { - "type": "null" - } - ] - } - }, - "required": [ - "data", - "type" - ], - "type": "object" - }, - "DropdownsValue": { - "properties": { "type": { - "description": "The type of value", + "description": "The field's type", "enum": [ - "dropdown-multi" + "enriched", + "global", + "list", + "relationship-intelligence" + ], + "examples": [ + "enriched" ], "type": "string" }, - "data": { - "description": "The value for many dropdown items", - "items": { - "$ref": "#/components/schemas/Dropdown" - }, - "type": "array", - "nullable": true - } - }, - "required": [ - "data", - "type" - ], - "type": "object" - }, - "Dropdown": { - "properties": { - "dropdownOptionId": { - "description": "Dropdown item's unique identifier", - "example": 1, - "format": "int64", - "type": "integer" + "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" + ] }, - "text": { - "description": "Dropdown item text", - "example": "first", - "type": "string" + "value": { + "$ref": "#/components/schemas/FieldValue" } }, "required": [ - "dropdownOptionId", - "text" + "enrichmentSource", + "id", + "name", + "type", + "value" ], "type": "object" }, - "DropdownValue": { - "properties": { - "type": { - "description": "The type of value", - "enum": [ - "dropdown" + "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/Dropdown" + "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" - }, - "RankedDropdown": { "properties": { - "dropdownOptionId": { - "description": "Dropdown item's unique identifier", - "example": 1, - "format": "int64", - "type": "integer" - }, - "text": { - "description": "Dropdown item text", - "example": "first", - "type": "string" - }, - "rank": { - "description": "Dropdown item rank", - "example": 0, + "id": { + "description": "The company's unique identifier", + "examples": [ + 1 + ], "format": "int64", "type": "integer" }, - "color": { - "description": "Dropdown item color", - "example": "white", - "type": "string", - "nullable": true - } - }, - "required": [ - "color", - "dropdownOptionId", - "rank", - "text" - ], - "type": "object" - }, - "RankedDropdownValue": { - "properties": { - "type": { - "description": "The type of value", - "enum": [ - "ranked-dropdown" + "name": { + "description": "The company's name", + "examples": [ + "Acme" ], "type": "string" }, - "data": { - "oneOf": [ - { - "$ref": "#/components/schemas/RankedDropdown" - }, - { - "type": "null" - } + "domain": { + "description": "The company's primary domain", + "examples": [ + "acme.co" + ], + "format": "hostname", + "type": [ + "string", + "null" ] - } - }, - "required": [ - "data", - "type" - ], - "type": "object" - }, - "TextsValue": { - "properties": { - "type": { - "description": "The type of value", - "enum": [ - "filterable-text-multi" + }, + "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": "string" + "type": "boolean" }, - "data": { - "description": "The value for many strings", + "fields": { + "description": "The fields associated with the company", "items": { - "type": "string" + "$ref": "#/components/schemas/Field" }, - "type": "array", - "nullable": true + "type": "array" } }, "required": [ - "data", - "type" + "domain", + "domains", + "id", + "isGlobal", + "name" ], "type": "object" }, - "TextValue": { - "properties": { - "type": { - "description": "The type of value", - "enum": [ - "filterable-text", - "text" - ], - "example": "filterable-text", - "type": "string" - }, - "data": { - "description": "The value for a string", - "type": "string", - "nullable": true + "Pagination": { + "examples": [ + { + "prevUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgYmVmb3JlOjo6Nw", + "nextUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgIGFmdGVyOjo6NA" } - }, - "required": [ - "data", - "type" ], - "type": "object" - }, - "DateValue": { "properties": { - "type": { - "description": "The type of value", - "enum": [ - "datetime" + "prevUrl": { + "description": "URL for the previous page", + "examples": [ + "https://api.affinity.co/v2/foo?cursor=ICAgICAgYmVmb3JlOjo6Nw" ], - "type": "string" + "format": "url", + "type": [ + "string", + "null" + ] }, - "data": { - "description": "The value for a date", - "format": "date-time", - "type": "string", - "nullable": true + "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" }, - "FloatsValue": { + "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": [ - "number-multi" - ], - "type": "string" - }, "data": { - "description": "The value for many numbers", + "description": "A page of Company results", "items": { - "type": "number" + "$ref": "#/components/schemas/Company" }, - "type": "array", - "nullable": true + "type": "array" + }, + "pagination": { + "$ref": "#/components/schemas/Pagination" } }, "required": [ "data", - "type" + "pagination" ], "type": "object" }, - "FloatValue": { - "properties": { - "type": { - "description": "The type of value", - "enum": [ - "number" - ], - "type": "string" - }, - "data": { - "description": "The value for a number", - "type": "number", - "nullable": true + "ValidationError": { + "examples": [ + { + "code": "validation", + "param": "limit", + "message": "🚨 Error! Sound the alarm! 🚨" } - }, - "required": [ - "data", - "type" ], - "type": "object" - }, - "LocationsValue": { "properties": { - "type": { - "description": "The type of value", - "enum": [ - "location-multi" - ], + "code": { + "description": "Error code", + "const": "validation", "type": "string" }, - "data": { - "description": "The values for many locations", - "items": { - "$ref": "#/components/schemas/Location" - }, - "type": "array", - "nullable": true + "message": { + "description": "Error message", + "type": "string" + }, + "param": { + "description": "Param the error refers to", + "type": "string" } }, "required": [ - "data", - "type" + "code", + "message", + "param" ], "type": "object" }, - "LocationValue": { - "properties": { - "type": { - "description": "The type of value", - "enum": [ - "location" - ], - "type": "string" - }, - "data": { - "oneOf": [ + "ValidationErrors": { + "description": "ValidationErrors model", + "examples": [ + { + "errors": [ { - "$ref": "#/components/schemas/Location" + "code": "validation", + "param": "limit", + "message": "🚨 Error! Sound the alarm! 🚨" }, { - "type": "null" + "code": "validation", + "param": "limit", + "message": "🚨 Error! Sound the alarm! 🚨" } ] } - }, - "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", + "errors": { + "description": "ValidationError errors", "items": { - "$ref": "#/components/schemas/CompanyData" + "$ref": "#/components/schemas/ValidationError" }, - "type": "array", - "nullable": true + "type": "array" } }, "required": [ - "data", - "type" + "errors" + ], + "type": "object" + }, + "AuthorizationError": { + "examples": [ + { + "code": "authorization", + "message": "🚨 Error! Sound the alarm! 🚨" + } ], - "type": "object" - }, - "CompanyData": { "properties": { - "id": { - "description": "The company's unique identifier", - "example": 1, - "format": "int64", - "type": "integer" - }, - "name": { - "description": "The company's name", - "example": "Acme", + "code": { + "description": "Error code", + "const": "authorization", "type": "string" }, - "domain": { - "description": "The company's primary domain", - "example": "acme.co", - "format": "hostname", + "message": { + "description": "Error message", "type": "string" } }, "required": [ - "domain", - "id", - "name" + "code", + "message" ], "type": "object" }, - "CompanyValue": { - "properties": { - "type": { - "description": "The type of value", - "enum": [ - "company" - ], - "type": "string" - }, - "data": { - "oneOf": [ + "AuthorizationErrors": { + "description": "AuthorizationErrors model", + "examples": [ + { + "errors": [ { - "$ref": "#/components/schemas/CompanyData" + "code": "authorization", + "message": "🚨 Error! Sound the alarm! 🚨" }, { - "type": "null" + "code": "authorization", + "message": "🚨 Error! Sound the alarm! 🚨" } ] } + ], + "properties": { + "errors": { + "description": "AuthorizationError errors", + "items": { + "$ref": "#/components/schemas/AuthorizationError" + }, + "type": "array" + } }, "required": [ - "data", - "type" + "errors" ], "type": "object" }, - "PersonsValue": { + "FieldMetadata": { + "examples": [ + { + "enrichmentSource": "affinity-data", + "valueType": "location", + "name": "Location", + "id": "affinity-data-location", + "type": "enriched" + } + ], "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": [ - "person-multi" + "enriched", + "global", + "list", + "relationship-intelligence" + ], + "examples": [ + "enriched" ], "type": "string" }, - "data": { - "description": "The values for many persons", - "items": { - "$ref": "#/components/schemas/PersonData" - }, - "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" + ] + }, + "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": [ - "data", - "type" + "enrichmentSource", + "id", + "name", + "type", + "valueType" ], "type": "object" }, - "PersonValue": { - "properties": { - "type": { - "description": "The type of value", - "enum": [ - "person" - ], - "type": "string" - }, - "data": { - "oneOf": [ + "FieldMetadataPaged": { + "description": "FieldMetadataPaged model", + "examples": [ + { + "pagination": { + "prevUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgYmVmb3JlOjo6Nw", + "nextUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgIGFmdGVyOjo6NA" + }, + "data": [ { - "$ref": "#/components/schemas/PersonData" + "enrichmentSource": "affinity-data", + "valueType": "location", + "name": "Location", + "id": "affinity-data-location", + "type": "enriched" }, { - "type": "null" + "enrichmentSource": "affinity-data", + "valueType": "location", + "name": "Location", + "id": "affinity-data-location", + "type": "enriched" } ] } + ], + "properties": { + "data": { + "description": "A page of FieldMetadata results", + "items": { + "$ref": "#/components/schemas/FieldMetadata" + }, + "type": "array" + }, + "pagination": { + "$ref": "#/components/schemas/Pagination" + } }, "required": [ "data", - "type" + "pagination" ], "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" + "List": { + "examples": [ + { + "name": "All companies", + "creatorId": 1, + "isPublic": false, + "id": 1, + "ownerId": 1 + } + ], + "properties": { + "id": { + "description": "The unique identifier for the list", + "examples": [ + 1 + ], + "format": "int64", + "type": "integer" }, - "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" - } - } - ] - } - ] + "name": { + "description": "The name of the list", + "examples": [ + "All companies" + ], + "type": "string" + }, + "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" + } }, + "required": [ + "creatorId", + "id", + "isPublic", + "name", + "ownerId" + ], + "type": "object" + }, + "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": { "data": { - "description": "A page of ListEntry results", + "description": "A page of List results", "items": { - "$ref": "#/components/schemas/ListEntry" + "$ref": "#/components/schemas/List" }, "type": "array" }, @@ -3849,71 +3920,83 @@ "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" + "examples": [ + { + "listId": 1, + "createdAt": "2023-01-01T00:00:00Z", + "creatorId": 1, + "id": 1, + "fields": [ + { + "enrichmentSource": "affinity-data", + "name": "Location", + "id": "affinity-data-location", + "type": "enriched", + "value": { + "data": { + "continent": "North America", + "country": "United States", + "streetAddress": "170 Columbus Ave", + "city": "San Francisco", + "state": "California" + }, + "type": "location" + } + }, + { + "enrichmentSource": "affinity-data", + "name": "Location", + "id": "affinity-data-location", + "type": "enriched", + "value": { + "data": { + "continent": "North America", + "country": "United States", + "streetAddress": "170 Columbus Ave", + "city": "San Francisco", + "state": "California" + }, + "type": "location" + } } - } - ] - }, + ] + } + ], "properties": { "id": { "description": "The list entry's unique identifier", - "example": 1, + "examples": [ + 1 + ], "format": "int64", "type": "integer" }, "listId": { "description": "The ID of the list that this list entry belongs to", - "example": 1, + "examples": [ + 1 + ], "format": "int64", "type": "integer" }, "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" + ] }, "fields": { "description": "The fields associated with the list entry", @@ -3932,35 +4015,103 @@ ], "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 + "ListEntryPaged": { + "description": "ListEntryPaged 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": [ + { + "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": { "data": { - "description": "A page of List results", + "description": "A page of ListEntry results", "items": { - "$ref": "#/components/schemas/List" + "$ref": "#/components/schemas/ListEntry" }, "type": "array" }, @@ -3974,289 +4125,173 @@ ], "type": "object" }, - "List": { - "example": { - "name": "All companies", - "creatorId": 1, - "isPublic": false, - "id": 1, - "ownerId": 1 - }, + "ListWithType": { + "description": "ListWithType model", + "examples": [ + { + "name": "All companies", + "creatorId": 1, + "isPublic": false, + "id": 1, + "ownerId": 1, + "type": "company" + } + ], "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" - } - }, - "required": [ - "creatorId", - "id", - "isPublic", - "name", - "ownerId" - ], - "type": "object" - }, - "Errors": { - "properties": { - "errors": { - "description": "Errors", - "items": { - "$ref": "#/components/schemas/Error" - }, - "type": "array", - "nullable": true - } - }, - "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" - }, - { - "$ref": "#/components/schemas/GenericError" - } - ] - }, - "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", + "description": "The entity type for this list", "enum": [ - "api-key" + "company", + "opportunity", + "person" ], - "example": "api-key", - "type": "string" - }, - "scopes": { - "description": "The scopes available to the current grant", - "example": [ - "api" + "examples": [ + "company" ], - "items": { - "type": "string" - }, - "type": "array" - }, - "createdAt": { - "description": "When the grant was created", - "example": "2023-01-01 00:00:00.000000000 Z", - "format": "date-time", "type": "string" } }, "required": [ - "createdAt", - "scopes", + "creatorId", + "id", + "isPublic", + "name", + "ownerId", "type" ], "type": "object" }, - "User": { - "example": { - "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": { - "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 ListWithType results", + "items": { + "$ref": "#/components/schemas/ListWithType" + }, + "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 - }, + "CompanyListEntry": { "properties": { "id": { - "description": "The tenant's unique identifier", - "example": 1, + "description": "The list entry's unique identifier", + "examples": [ + 1 + ], "format": "int64", "type": "integer" }, - "name": { - "description": "The name of the tenant", - "example": "Contoso Ltd.", + "type": { + "description": "The entity type for this list entry", + "const": "company", + "examples": [ + "company" + ], "type": "string" }, - "subdomain": { - "description": "The tenant's subdomain under affinity.co", - "example": "contoso", - "format": "hostname", - "type": "string" - } - }, - "required": [ - "id", - "name", - "subdomain" - ], - "type": "object" - }, - "WhoAmI": { - "description": "WhoAmI model", - "example": { - "grant": { - "createdAt": "2023-01-01 00:00:00.000000000 Z", - "scopes": [ - "api" + "createdAt": { + "description": "The date that the list entry was created", + "examples": [ + "2023-01-01T00:00:00Z" ], - "type": "api-key" - }, - "user": { - "firstName": "John", - "lastName": "Smith", - "emailAddress": "john.smith@contoso.com", - "id": 1 - }, - "tenant": { - "name": "Contoso Ltd.", - "subdomain": "contoso", - "id": 1 - } - }, - "properties": { - "tenant": { - "$ref": "#/components/schemas/Tenant" + "format": "date-time", + "type": "string" }, - "user": { - "$ref": "#/components/schemas/User" + "creatorId": { + "description": "The ID of the user that created this list entry", + "examples": [ + 1 + ], + "format": "int64", + "type": [ + "integer", + "null" + ] }, - "grant": { - "$ref": "#/components/schemas/Grant" + "entity": { + "$ref": "#/components/schemas/Company" } }, "required": [ - "grant", - "tenant", - "user" + "createdAt", + "creatorId", + "entity", + "id", + "type" ], "type": "object" }, @@ -4264,18 +4299,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 +4335,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 +4385,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 +4564,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 diff --git a/openapitools.json b/openapitools.json index 38fe995..43808e7 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-20240929.161806-74", + "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/v2/generated/.openapi-generator/FILES b/src/v2/generated/.openapi-generator/FILES index ff23f31..f129fed 100644 --- a/src/v2/generated/.openapi-generator/FILES +++ b/src/v2/generated/.openapi-generator/FILES @@ -25,6 +25,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 @@ -38,8 +39,6 @@ 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 @@ -48,13 +47,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 @@ -68,9 +63,10 @@ models/LocationValue.ts models/LocationsValue.ts models/Meeting.ts models/MethodNotAllowedError.ts -models/ModelError.ts +models/NotAcceptableError.ts models/NotFoundError.ts models/NotFoundErrors.ts +models/NotImplementedError.ts models/ObjectSerializer.ts models/Opportunity.ts models/OpportunityListEntry.ts @@ -93,7 +89,8 @@ models/ServerError.ts models/Tenant.ts models/TextValue.ts models/TextsValue.ts -models/TooManyMultipartFilesError.ts +models/UnprocessableEntityError.ts +models/UnsupportedMediaTypeError.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..77e386c 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': AuthenticationErrorCodeEnum; /** * Error message */ - 'message'?: string | null; + 'message': string; static readonly discriminator: string | undefined = undefined; @@ -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/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..be95b91 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': AuthorizationErrorCodeEnum; /** * Error message */ - 'message'?: string | null; + 'message': string; static readonly discriminator: string | undefined = undefined; @@ -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/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/EmptyMessageBodyError.ts b/src/v2/generated/models/BadRequestError.ts similarity index 76% rename from src/v2/generated/models/EmptyMessageBodyError.ts rename to src/v2/generated/models/BadRequestError.ts index f908260..37166a3 100644 --- a/src/v2/generated/models/EmptyMessageBodyError.ts +++ b/src/v2/generated/models/BadRequestError.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 @@ -12,15 +12,15 @@ import { HttpFile } from '../http/http.ts'; -export class EmptyMessageBodyError { +export class BadRequestError { /** * Error code */ - 'code'?: string | null; + 'code': BadRequestErrorCodeEnum; /** * Error message */ - 'message'?: string | null; + 'message': string; static readonly discriminator: string | undefined = undefined; @@ -30,7 +30,7 @@ export class EmptyMessageBodyError { { "name": "code", "baseName": "code", - "type": "string", + "type": "BadRequestErrorCodeEnum", "format": "" }, { @@ -41,9 +41,14 @@ export class EmptyMessageBodyError { } ]; static getAttributeTypeMap() { - return EmptyMessageBodyError.attributeTypeMap; + return BadRequestError.attributeTypeMap; } 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 57a9e9e..4d68ad0 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 diff --git a/src/v2/generated/models/CompaniesValue.ts b/src/v2/generated/models/CompaniesValue.ts index 3bb94f7..5a14061 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 diff --git a/src/v2/generated/models/Company.ts b/src/v2/generated/models/Company.ts index 729450b..e3ec270 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 @@ -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 9963028..0a0ebae 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 @@ -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/CompanyListEntry.ts b/src/v2/generated/models/CompanyListEntry.ts index b73ef76..0a50930 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 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..1798023 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 diff --git a/src/v2/generated/models/ConflictError.ts b/src/v2/generated/models/ConflictError.ts index 2113fe6..59dff09 100644 --- a/src/v2/generated/models/ConflictError.ts +++ b/src/v2/generated/models/ConflictError.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 ConflictError { /** * Error code */ - 'code'?: string | null; + 'code': ConflictErrorCodeEnum; /** * Error message */ - 'message'?: string | null; + 'message': string; static readonly discriminator: string | undefined = undefined; @@ -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 b9e6545..11f3776 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 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..326822e 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 diff --git a/src/v2/generated/models/DropdownsValue.ts b/src/v2/generated/models/DropdownsValue.ts index 2430f5e..49aa1a9 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 diff --git a/src/v2/generated/models/Email.ts b/src/v2/generated/models/Email.ts index bacc6ac..7220b8e 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 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 616f308..8243ac5 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 5b14f0d..4622f43 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..3220523 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 diff --git a/src/v2/generated/models/FloatsValue.ts b/src/v2/generated/models/FloatsValue.ts index 8c2d9c7..b0f71cf 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 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..46fbef3 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 diff --git a/src/v2/generated/models/Grant.ts b/src/v2/generated/models/Grant.ts index 2287cf5..69866c8 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 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..3c3fad6 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 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..f948ad5 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 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..744c164 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 diff --git a/src/v2/generated/models/LocationsValue.ts b/src/v2/generated/models/LocationsValue.ts index b1f9515..60110ee 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 diff --git a/src/v2/generated/models/Meeting.ts b/src/v2/generated/models/Meeting.ts index 5359c8a..dc738c9 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 diff --git a/src/v2/generated/models/MethodNotAllowedError.ts b/src/v2/generated/models/MethodNotAllowedError.ts index 4dd3592..95682fd 100644 --- a/src/v2/generated/models/MethodNotAllowedError.ts +++ b/src/v2/generated/models/MethodNotAllowedError.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 MethodNotAllowedError { /** * Error code */ - 'code'?: string | null; + 'code': MethodNotAllowedErrorCodeEnum; /** * Error message */ - 'message'?: string | null; + 'message': string; static readonly discriminator: string | undefined = undefined; @@ -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/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/InvalidMessageBodyError.ts b/src/v2/generated/models/NotAcceptableError.ts similarity index 75% rename from src/v2/generated/models/InvalidMessageBodyError.ts rename to src/v2/generated/models/NotAcceptableError.ts index c4337a2..f5caa67 100644 --- a/src/v2/generated/models/InvalidMessageBodyError.ts +++ b/src/v2/generated/models/NotAcceptableError.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 @@ -12,15 +12,15 @@ import { HttpFile } from '../http/http.ts'; -export class InvalidMessageBodyError { +export class NotAcceptableError { /** * Error code */ - 'code'?: string | null; + 'code': NotAcceptableErrorCodeEnum; /** * Error message */ - 'message'?: string | null; + 'message': string; static readonly discriminator: string | undefined = undefined; @@ -30,7 +30,7 @@ export class InvalidMessageBodyError { { "name": "code", "baseName": "code", - "type": "string", + "type": "NotAcceptableErrorCodeEnum", "format": "" }, { @@ -41,9 +41,14 @@ export class InvalidMessageBodyError { } ]; static getAttributeTypeMap() { - return InvalidMessageBodyError.attributeTypeMap; + return NotAcceptableError.attributeTypeMap; } 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 25c81ef..38d1841 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': NotFoundErrorCodeEnum; /** * Error message */ - 'message'?: string | null; + 'message': string; static readonly discriminator: string | undefined = undefined; @@ -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/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/GenericError.ts b/src/v2/generated/models/NotImplementedError.ts similarity index 75% rename from src/v2/generated/models/GenericError.ts rename to src/v2/generated/models/NotImplementedError.ts index a97a70a..4a1f6cd 100644 --- a/src/v2/generated/models/GenericError.ts +++ b/src/v2/generated/models/NotImplementedError.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 @@ -12,15 +12,15 @@ import { HttpFile } from '../http/http.ts'; -export class GenericError { +export class NotImplementedError { /** * Error code */ - 'code'?: string | null; + 'code': NotImplementedErrorCodeEnum; /** * Error message */ - 'message'?: string | null; + 'message': string; static readonly discriminator: string | undefined = undefined; @@ -30,7 +30,7 @@ export class GenericError { { "name": "code", "baseName": "code", - "type": "string", + "type": "NotImplementedErrorCodeEnum", "format": "" }, { @@ -41,9 +41,14 @@ export class GenericError { } ]; static getAttributeTypeMap() { - return GenericError.attributeTypeMap; + return NotImplementedError.attributeTypeMap; } 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 a7d9e8a..d2f6aa9 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'; @@ -16,8 +17,6 @@ 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 +25,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'; @@ -46,9 +41,10 @@ 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/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'; @@ -70,17 +66,19 @@ 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/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, 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'; @@ -88,14 +86,12 @@ import { CompanyData } from '../models/CompanyData.ts'; import { CompanyListEntry , CompanyListEntryTypeEnum } from '../models/CompanyListEntry.ts'; import { CompanyPaged } from '../models/CompanyPaged.ts'; import { CompanyValue, CompanyValueTypeEnum } from '../models/CompanyValue.ts'; -import { ConflictError } from '../models/ConflictError.ts'; +import { ConflictError, ConflictErrorCodeEnum } from '../models/ConflictError.ts'; import { DateValue, DateValueTypeEnum } 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 { Field , FieldTypeEnum , FieldEnrichmentSourceEnum } from '../models/Field.ts'; import { FieldMetadata , FieldMetadataTypeEnum , FieldMetadataEnrichmentSourceEnum , FieldMetadataValueTypeEnum } from '../models/FieldMetadata.ts'; import { FieldMetadataPaged } from '../models/FieldMetadataPaged.ts'; @@ -104,13 +100,9 @@ import { FloatValue, FloatValueTypeEnum } from '../models/FloatValue.ts'; import { FloatsValue, FloatsValueTypeEnum } 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 { 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 { List } from '../models/List.ts'; import { ListEntry } from '../models/ListEntry.ts'; import { ListEntryPaged } from '../models/ListEntryPaged.ts'; @@ -123,10 +115,11 @@ 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 { NotFoundError } from '../models/NotFoundError.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, NotImplementedErrorCodeEnum } from '../models/NotImplementedError.ts'; import { Opportunity } from '../models/Opportunity.ts'; import { OpportunityListEntry , OpportunityListEntryTypeEnum } from '../models/OpportunityListEntry.ts'; import { OpportunityPaged } from '../models/OpportunityPaged.ts'; @@ -141,16 +134,17 @@ import { PersonsValue, PersonsValueTypeEnum } from '../models/PersonsValue.ts import { PhoneCall, PhoneCallTypeEnum } from '../models/PhoneCall.ts'; import { RankedDropdown } from '../models/RankedDropdown.ts'; import { RankedDropdownValue, RankedDropdownValueTypeEnum } from '../models/RankedDropdownValue.ts'; -import { RateLimitError } from '../models/RateLimitError.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, TextsValueTypeEnum } from '../models/TextsValue.ts'; -import { TooManyMultipartFilesError } from '../models/TooManyMultipartFilesError.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'; @@ -167,11 +161,15 @@ let primitives = [ ]; let enumsMap: Set = new Set([ + "AuthenticationErrorCodeEnum", + "AuthorizationErrorCodeEnum", + "BadRequestErrorCodeEnum", "ChatMessageTypeEnum", "ChatMessageDirectionEnum", "CompaniesValueTypeEnum", "CompanyListEntryTypeEnum", "CompanyValueTypeEnum", + "ConflictErrorCodeEnum", "DateValueTypeEnum", "DropdownValueTypeEnum", "DropdownsValueTypeEnum", @@ -194,6 +192,10 @@ let enumsMap: Set = new Set([ "LocationValueTypeEnum", "LocationsValueTypeEnum", "MeetingTypeEnum", + "MethodNotAllowedErrorCodeEnum", + "NotAcceptableErrorCodeEnum", + "NotFoundErrorCodeEnum", + "NotImplementedErrorCodeEnum", "OpportunityListEntryTypeEnum", "PersonTypeEnum", "PersonDataTypeEnum", @@ -202,9 +204,14 @@ let enumsMap: Set = new Set([ "PersonsValueTypeEnum", "PhoneCallTypeEnum", "RankedDropdownValueTypeEnum", + "RateLimitErrorCodeEnum", "SavedViewTypeEnum", + "ServerErrorCodeEnum", "TextValueTypeEnum", "TextsValueTypeEnum", + "UnprocessableEntityErrorCodeEnum", + "UnsupportedMediaTypeErrorCodeEnum", + "ValidationErrorCodeEnum", ]); let typeMap: {[index: string]: any} = { @@ -213,6 +220,7 @@ let typeMap: {[index: string]: any} = { "AuthenticationErrors": AuthenticationErrors, "AuthorizationError": AuthorizationError, "AuthorizationErrors": AuthorizationErrors, + "BadRequestError": BadRequestError, "ChatMessage": ChatMessage, "CompaniesValue": CompaniesValue, "Company": Company, @@ -226,8 +234,6 @@ let typeMap: {[index: string]: any} = { "DropdownValue": DropdownValue, "DropdownsValue": DropdownsValue, "Email": Email, - "EmptyMessageBodyError": EmptyMessageBodyError, - "Errors": Errors, "Field": Field, "FieldMetadata": FieldMetadata, "FieldMetadataPaged": FieldMetadataPaged, @@ -236,13 +242,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, @@ -256,9 +258,10 @@ let typeMap: {[index: string]: any} = { "LocationsValue": LocationsValue, "Meeting": Meeting, "MethodNotAllowedError": MethodNotAllowedError, - "ModelError": ModelErrorClass, + "NotAcceptableError": NotAcceptableError, "NotFoundError": NotFoundError, "NotFoundErrors": NotFoundErrors, + "NotImplementedError": NotImplementedError, "Opportunity": Opportunity, "OpportunityListEntry": OpportunityListEntry, "OpportunityPaged": OpportunityPaged, @@ -280,7 +283,8 @@ let typeMap: {[index: string]: any} = { "Tenant": Tenant, "TextValue": TextValue, "TextsValue": TextsValue, - "TooManyMultipartFilesError": TooManyMultipartFilesError, + "UnprocessableEntityError": UnprocessableEntityError, + "UnsupportedMediaTypeError": UnsupportedMediaTypeError, "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..818f27b 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 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..9c92a40 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 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..cd81d97 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 diff --git a/src/v2/generated/models/PersonsValue.ts b/src/v2/generated/models/PersonsValue.ts index efb40a7..1075624 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 diff --git a/src/v2/generated/models/PhoneCall.ts b/src/v2/generated/models/PhoneCall.ts index e405470..3d3907a 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 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..b7589a0 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 diff --git a/src/v2/generated/models/RateLimitError.ts b/src/v2/generated/models/RateLimitError.ts index 0fcd615..1123e54 100644 --- a/src/v2/generated/models/RateLimitError.ts +++ b/src/v2/generated/models/RateLimitError.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 RateLimitError { /** * Error code */ - 'code'?: string | null; + 'code': RateLimitErrorCodeEnum; /** * Error message */ - 'message'?: string | null; + 'message': string; static readonly discriminator: string | undefined = undefined; @@ -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/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 index bd13722..dfc73d5 100644 --- a/src/v2/generated/models/ServerError.ts +++ b/src/v2/generated/models/ServerError.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 ServerError { /** * Error code */ - 'code'?: string | null; + 'code': ServerErrorCodeEnum; /** * Error message */ - 'message'?: string | null; + 'message': string; static readonly discriminator: string | undefined = undefined; @@ -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/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..b6e8685 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 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/InvalidAcceptHeaderError.ts b/src/v2/generated/models/UnprocessableEntityError.ts similarity index 76% rename from src/v2/generated/models/InvalidAcceptHeaderError.ts rename to src/v2/generated/models/UnprocessableEntityError.ts index 508dde2..3ce4b79 100644 --- a/src/v2/generated/models/InvalidAcceptHeaderError.ts +++ b/src/v2/generated/models/UnprocessableEntityError.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 @@ -12,15 +12,15 @@ import { HttpFile } from '../http/http.ts'; -export class InvalidAcceptHeaderError { +export class UnprocessableEntityError { /** * Error code */ - 'code'?: string | null; + 'code': UnprocessableEntityErrorCodeEnum; /** * Error message */ - 'message'?: string | null; + 'message': string; static readonly discriminator: string | undefined = undefined; @@ -30,7 +30,7 @@ export class InvalidAcceptHeaderError { { "name": "code", "baseName": "code", - "type": "string", + "type": "UnprocessableEntityErrorCodeEnum", "format": "" }, { @@ -41,9 +41,14 @@ export class InvalidAcceptHeaderError { } ]; static getAttributeTypeMap() { - return InvalidAcceptHeaderError.attributeTypeMap; + return UnprocessableEntityError.attributeTypeMap; } 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/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..5fd4f83 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': ValidationErrorCodeEnum; /** * Error message */ - 'message'?: string | null; + 'message': string; /** * Param the error refers to */ - 'param'?: string | null; + 'param': string; static readonly discriminator: string | undefined = undefined; @@ -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/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..6577a7b 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' @@ -16,8 +17,6 @@ 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 +25,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' @@ -46,9 +41,10 @@ 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/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' @@ -70,7 +66,8 @@ 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/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 013dde9..5d6edad 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'; @@ -19,8 +20,6 @@ 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 +28,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,9 +44,10 @@ 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 { 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'; @@ -73,7 +69,8 @@ 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 { 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'; diff --git a/src/v2/generated/types/ObservableAPI.ts b/src/v2/generated/types/ObservableAPI.ts index c0c5ca1..af22821 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'; @@ -20,8 +21,6 @@ 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 +29,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'; @@ -50,9 +45,10 @@ 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 { 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'; @@ -74,7 +70,8 @@ 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 { 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'; diff --git a/src/v2/generated/types/PromiseAPI.ts b/src/v2/generated/types/PromiseAPI.ts index e2881af..45db2b9 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'; @@ -19,8 +20,6 @@ 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 +28,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,9 +44,10 @@ 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 { 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'; @@ -73,7 +69,8 @@ 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 { 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';