Affinity API Essential Guide

What type of API does Affinity provide?

REST API

Affinity provides a RESTful API. The key points are:

• It is described as a "full-featured RESTful API" that provides reading and writing functionality for each object type in Affinity.
• All requests use the base URL of https://api.affinity.co/.
• Responses are provided as JSON objects.
• It uses HTTP Basic Auth for authentication, where you provide your API key as the password.

Key Characteristics

• RESTful architecture
• JSON responses
• HTTP Basic Auth
• Full CRUD (Create, Read, Update, Delete) functionality

API Documentation

Affinity provides detailed API documentation, including:

• Authentication instructions
• Error codes and meanings
• Common use cases
• Webhook functionality

Best Practices

When using Affinity's REST API:

• Generate and securely store an API secret key from the Affinity web app settings
• Include the API key with every request
• Handle potential error responses (401 Unauthorized, 403 Forbidden, etc.)
• Review the documentation for specific endpoints and parameters

Does the Affinity API have webhooks?

Yes, the official Affinity API does have webhooks. Here are the key points about Affinity's webhook functionality:

Webhook Support

• Affinity provides webhook support through their API V1 (not currently available in API V2).

Event Types

You can subscribe to the following types of webhook events:

• Organization events (created, updated, deleted, merged)
• Person events (created, updated, deleted)
• Opportunity events (created, updated, deleted)
• List events (created, updated, deleted)
• List Entry events (created, updated, deleted)
• Field events (created, updated, deleted)
• Field Value events (created, updated, deleted)
• Note events (created, updated, deleted)
• File events (created, updated, deleted)

Key Points

• There is a limit of three webhook subscriptions per Affinity instance.
• Webhook events fire immediately after the corresponding action takes place.
• You can subscribe to all events or specify particular events you want to receive.
• Webhook subscriptions can be created, updated, and managed through the API.
• Payload responses are generally formatted the same for each webhook event type (created, updated, deleted), with a few exceptions.

Best Practices

• Use webhooks to keep your external systems in sync with changes in your Affinity data.
• Be mindful of the webhook subscription limit and plan your integrations accordingly.
• Handle webhook events asynchronously to avoid performance issues in your application.
• Implement proper error handling and retries for webhook processing.

To set up and manage webhooks, you'll need to use the Affinity API V1. The API documentation provides detailed information on how to create, update, and manage webhook subscriptions.

Rate Limits and other limitations

Based on the search results provided, here are the key points about the API Rate Limits of the Affinity API:

Per-Minute Limits (User-Level)

• The Affinity API has a per-minute rate limit of 900 requests per user [1][3].
• This limit may be temporarily lowered to manage API availability [1][3].

Monthly Limits (Account-Level)

• There is a monthly account-level limit on API calls [1].
• For Professional tier customers who signed up before July 5, 2023, this limit is 40,000 calls per month [1].
• The monthly limit resets at the end of each calendar month [1].

Rate Limit Information

• You can get rate limit information by making a GET request to the /rate-limit endpoint [1].
• Each API call includes rate limit information in the response headers [1][3].

Rate Limit Headers

The following headers are included in every API response [1][3]:

• X-Ratelimit-Limit-User: Number of requests allowed per minute for the user
• X-Ratelimit-Limit-User-Remaining: Number of requests remaining for the user
• X-Ratelimit-Limit-User-Reset: Time in seconds before the limit resets for the user
• X-Ratelimit-Limit-Org: Number of requests allowed per month for the organization
• X-Ratelimit-Limit-Org-Remaining: Number of requests remaining for the organization
• X-Ratelimit-Limit-Org-Reset: Time in seconds before the limit resets for the organization

Exceeding Rate Limits

• If you exceed the rate limits, subsequent requests will return an error code of 429 (Too Many Requests) [1][3].
• It's recommended to design your application to handle 429 errors [1][3].

Additional Notes

• The /rate-limit and /auth/whoami endpoints are exempt from organization-level monthly rate limits [1].
• There is a limit of three webhook subscriptions per Affinity instance [1].

Best Practices

• To reduce API calls, create initial backfills with the REST API, then use Webhooks to keep data synced [1].
• For large lists, use page_size and page_token parameters in the GET /lists/{list_id}/list-entries endpoint to improve performance [1].

It's important to note that these rate limits apply to both versions of the Affinity API (v1 and v2) [1][3]. If you need higher rate limits, it's recommended to contact Affinity support for assistance [1].

Latest API Version

Based on the search results provided, the most recent version of the Affinity API is version 2 (v2). Here are the key points to consider:

Key Points

1. Affinity API v2 is the latest version, introduced as a newly-improved API platform.

2. API v2 is not at feature parity with API v1, but Affinity will continue to add functionality to v2 over time.

3. API v1 is still available alongside v2 and has not been deprecated.

4. API v2 uses bearer authentication, which is different from API v1's basic authentication.

5. API v2 is only available on select Affinity license types, including Scale, Advanced, and Enterprise tiers.

Additional Information

• API v2 offers a more intuitive API structure, requiring fewer API calls and fewer endpoints for the same data compared to v1.
• API v2 is built on a new platform for better performance and reliability.
• API v2 provides an OpenAPI specification, which is not available for v1.
• Documentation for both API v1 and v2 is available in the Affinity API Documentation Center.

It's important to note that while v2 is the most recent version, it may not have all the features of v1 yet. Depending on your specific needs, you may need to use both versions or stick with v1 for certain functionalities until v2 reaches feature parity.

How to get a Affinity developer account and API Keys?

To get a developer account for Affinity to create an API integration, here are the key steps:

1. Ensure you have the proper permissions:

   • You must have the "Generate an API key" permission in your Affinity account.
   • Most users with API access have this by default, but you may need to contact your Affinity admin if you don't have it.

2. Generate an API key:

   • Log into the Affinity web app
   • Navigate to the Settings page
   • Look for the API key generation section
   • Follow the prompts to generate a new API key

3. Keep your API key secure:

   • Your API key allows access to read data and perform actions in Affinity on your behalf, so treat it like a password.
   • Affinity currently supports one API key per user in your account.

4. Use the API key for authentication:

   • Affinity API v2 uses bearer authentication.
   • Include your API key as the bearer token in API requests.

5. Be aware of endpoint-specific permissions:

   • Many API endpoints require additional permissions beyond just having an API key.
   • These map to in-product permissions and are managed by your Affinity admin.

6. Review the API documentation:

   • Familiarize yourself with the available endpoints and data models.
   • The base URL for all API requests is https://api.affinity.co.
   • All v2 endpoint paths start with /v2.

7. Consider partner restrictions:

   • The API supports pulling data from Affinity Data fields and select Dealroom fields.
   • Some data from certain partners may not be accessible via the API due to agreements.

Key points to consider:

• Ensure you have the proper account type that includes API access.
• Be aware of any rate limits or usage restrictions.
• Follow best practices for securing and rotating your API key.

If you need to request a developer account or have questions about API access, it's best to contact Affinity support directly or speak with your account representative.

What can you do with the Affinity API?

Based on the search results, here are the key data models you can interact with using the Affinity API, along with what is possible for each:

Persons

• Retrieve person data including name, contact info, etc.
• Access global fields and list-specific fields for persons
• Get relationship intelligence data like:
  • First/last email dates
  • First/last meeting dates
  • First/last chat message dates
  • Next scheduled meeting
  • Source of introduction
  • Associated organizations
• Create, update, and delete person records
• Add persons to lists

Organizations (Companies)

• Retrieve organization data including name, industry, etc.
• Access global fields and list-specific fields for organizations
• Get relationship intelligence data similar to persons
• Access some Dealroom.co enrichment data
• Create, update, and delete organization records
• Add organizations to lists

Opportunities

• Retrieve basic opportunity data like name and associated list
• Access global fields and list-specific fields for opportunities
• Get associated persons and companies
• Create, update, and delete opportunity records
• Add opportunities to lists

Lists

• Create and manage lists of persons, organizations, or opportunities
• Set list permissions and ownership
• Add/remove list entries (rows)
• Manage list-specific fields (columns)

List Entries

• Retrieve and update data for specific rows on lists
• Access both global and list-specific field data

Fields

• Get metadata on global, list-specific, and enriched fields
• Create and manage custom fields

Other

• Access some relationship intelligence data like interaction history
• Retrieve Affinity Data enrichment for companies and persons
• Work with saved views on lists

The API allows you to perform CRUD operations on most of these data models, with some limitations around certain enriched data sources. The core functionality centers around managing persons, organizations, opportunities and the lists/fields used to organize that data.