Skip to main content

Connect Affinity

Affinity connects with an API key issued by your Affinity account. Calls use that key owner's permissions and your Affinity account's API quota.

After you connect Affinity, you can add its tools to a qbash MCP server for ChatGPT, Claude and other MCP clients, or call it from a Python task. The Affinity MCP server page lists what the connector can do.

Create an Affinity API key​

  1. Sign in to Affinity and open Settings → Manage Apps.
  2. Create an app with a name that identifies its use in qbash, then generate its API key. Affinity's key setup instructions cover the current form.
  3. Copy the API key. Keep it private.
  4. If you cannot create a key, ask your Affinity admin for the Generate an API key permission and confirm your plan includes API access.

Affinity's published API limits list no API calls for Essentials, 100,000 calls per month for Scale and Advanced, and unlimited monthly calls for Enterprise. All eligible plans still have per-user minute limits and account concurrency limits. Confirm your own contract with Affinity if you use a legacy plan.

Your key can access only records the key owner can see in Affinity. Export reads, including saved-view entries, require Export data from Lists. Some fields depend on the data sources and features licensed to your account. A permission refusal does not mean that the key has expired.

Add the connection in qbash​

  1. Open Connectors → Affinity → Connect.
  2. Enter a credential name and paste the API key into API Key.
  3. If the key has an IP allowlist, select Requires static egress IP and confirm that your Affinity allowlist includes qbash's static egress addresses.
  4. Save the connection. qbash checks the key with Affinity's account endpoint and encrypts the stored key.
  5. In each task, open Resources → Integrations and explicitly select this Affinity credential.

Affinity connection form with empty credential fields

Read organizations​

This task reads one page without changing your CRM:

result = qbash.integrations.affinity.search_organizations(
    page_size=10,
    with_interaction_dates=True,
)
organizations = result["organizations"]
print("Organizations on this page:", len(organizations))
print("More pages:", result.get("next_page_token") is not None)

To continue, pass next_page_token as page_token with the same search filters. The printed organization count covers the current page.

For a filtered list with inline fields, call list_saved_views(list_id=...), choose an existing sheet view, then call get_saved_view_entries(list_id=..., view_id=..., limit=10). Saved-view filters and selected columns apply. View sort order is not preserved. These V2 reads return next_cursor, which you pass as cursor, and keep Affinity's camelCase field names and typed value objects.

See the Task SDK Reference for all methods and parameters.

Records, limits and errors​

  • V1 person and organization enrichment flags retain the related data supplied by Affinity. Null attributes may be omitted, so use .get() for optional fields.
  • Interaction reads require one type and a start/end time range of at most one year. Use meeting, call, chat or email, and ISO 8601 timestamps such as 2026-09-01T00:00:00Z.
  • Notes may contain HTML, Markdown or plain text. File reads return metadata, including size in bytes, rather than file contents.
  • get_fields() returns all accessible global and list definitions when no list ID is given. Definitions and field-value reads are complete collections without paging.
  • V1 inline field reads stop after 50 entries. Failed field reads return field_values="not_fetched" with field_values_error. Entity membership fallback scans at most 20 lists and one page per list, and reports truncated=True when coverage is incomplete.
  • Field-name filters resolve names from field definitions when needed. This can add an API request. Field history works only for definitions with track_changes=True.
  • V2 enriched-field endpoints are vendor beta endpoints. qbash pins V2 requests to 2026-09-17.
  • get_rate_limit() reports available quota. Its reset values are seconds until reset. V1 and V2 use the same quota pool. A 429 requires waiting for capacity to reset.

Replace or reconnect a key​

If a key is revoked or Affinity returns 401, generate a replacement in Manage Apps, then edit the qbash connection and replace its API key. qbash validates the replacement. Renaming the connection preserves the stored key.

For 403 errors, check the key owner's record access, export permission, plan and IP allowlist before replacing the key. Affinity's public REST API documents API-key authentication. qbash does not require a separate OAuth app for this connector.

Last updated on