Skip to content

Client

Affinity

Synchronous Affinity API client.

Provides access to all Affinity API functionality with a clean, Pythonic interface. Uses V2 API where available, falls back to V1 for operations not yet supported in V2.

Example 
from affinity import Affinity

# Initialize with API key
client = Affinity(api_key="your-api-key")

# Use as context manager for automatic cleanup
with Affinity(api_key="your-api-key") as client:
    # Get all companies
    for company in client.companies.all():
        print(company.name)

    # Get a specific person with field data
    person = client.persons.get(
        PersonId(12345),
        field_types=["enriched", "global"]
    )

    # Add a company to a list
    entries = client.lists.entries(ListId(789))
    entry = entries.add_company(CompanyId(456))

    # Update field values
    entries.update_field_value(
        entry.id,
        FieldId(101),
        "New value"
    )

Attributes:

Name Type Description
companies CompanyService

Company (organization) operations
persons PersonService

Person (contact) operations
lists ListService

List operations
notes NoteService

Note operations
reminders ReminderService

Reminder operations
webhooks WebhookService

Webhook subscription operations
interactions InteractionService

Interaction (email, meeting, etc.) operations
fields FieldService

Custom field operations
field_values FieldValueService

Field value operations
field_value_changes FieldValueChangesService

Field value change history operations
files EntityFileService

Entity file operations
relationships RelationshipStrengthService

Relationship strength queries
auth AuthService

Authentication and rate limit info
Source code in affinity/client.py 
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
class Affinity:
    """
    Synchronous Affinity API client.

    Provides access to all Affinity API functionality with a clean,
    Pythonic interface. Uses V2 API where available, falls back to V1
    for operations not yet supported in V2.

    Example:
        ```python
        from affinity import Affinity

        # Initialize with API key
        client = Affinity(api_key="your-api-key")

        # Use as context manager for automatic cleanup
        with Affinity(api_key="your-api-key") as client:
            # Get all companies
            for company in client.companies.all():
                print(company.name)

            # Get a specific person with field data
            person = client.persons.get(
                PersonId(12345),
                field_types=["enriched", "global"]
            )

            # Add a company to a list
            entries = client.lists.entries(ListId(789))
            entry = entries.add_company(CompanyId(456))

            # Update field values
            entries.update_field_value(
                entry.id,
                FieldId(101),
                "New value"
            )
        ```

    Attributes:
        companies: Company (organization) operations
        persons: Person (contact) operations
        lists: List operations
        notes: Note operations
        reminders: Reminder operations
        webhooks: Webhook subscription operations
        interactions: Interaction (email, meeting, etc.) operations
        fields: Custom field operations
        field_values: Field value operations
        field_value_changes: Field value change history operations
        files: Entity file operations
        relationships: Relationship strength queries
        auth: Authentication and rate limit info
    """

    def __init__(
        self,
        api_key: str,
        *,
        v1_base_url: str = V1_BASE_URL,
        v2_base_url: str = V2_BASE_URL,
        v1_auth_mode: Literal["bearer", "basic"] = "bearer",
        transport: httpx.BaseTransport | None = None,
        async_transport: httpx.AsyncBaseTransport | None = None,
        enable_beta_endpoints: bool = False,
        allow_insecure_download_redirects: bool = False,
        expected_v2_version: str | None = None,
        timeout: float = 30.0,
        max_retries: int = 3,
        enable_cache: bool = False,
        cache_ttl: float = 300.0,
        log_requests: bool = False,
        on_request: RequestHook | None = None,
        on_response: ResponseHook | None = None,
        on_error: ErrorHook | None = None,
        on_event: AnyEventHook | None = None,
        hook_error_policy: Literal["swallow", "raise"] = "swallow",
        policies: Policies | None = None,
    ):
        """
        Initialize the Affinity client.

        Args:
            api_key: Your Affinity API key
            v1_base_url: V1 API base URL (default: https://api.affinity.co)
            v2_base_url: V2 API base URL (default: https://api.affinity.co/v2)
            v1_auth_mode: Auth mode for V1 API ("bearer" or "basic")
            transport: Optional `httpx` transport (advanced; useful for mocking in tests)
            async_transport: Optional async `httpx` transport (advanced; useful for mocking in
                tests)
            enable_beta_endpoints: Enable beta V2 endpoints
            allow_insecure_download_redirects: Allow `http://` redirects for file downloads.
                Not recommended; prefer HTTPS-only downloads.
            expected_v2_version: Expected V2 API version for diagnostics (e.g.,
                "2024-01-01"). Used to detect version compatibility issues.
                See TR-015.
            timeout: Request timeout in seconds
            max_retries: Maximum retries for rate-limited requests
            enable_cache: Enable response caching for field metadata
            cache_ttl: Cache TTL in seconds
            log_requests: Log all HTTP requests (for debugging)
            on_request: Hook called before each request (DX-008)
            on_response: Hook called after each response (DX-008)
            on_error: Hook called when a request raises (DX-008)
            on_event: Event hook called for request/response lifecycle events (DX-008)
            hook_error_policy: What to do if hooks raise ("swallow" or "raise")
            policies: Client policies (e.g., disable writes)
        """
        config = ClientConfig(
            api_key=api_key,
            v1_base_url=v1_base_url,
            v2_base_url=v2_base_url,
            v1_auth_mode=v1_auth_mode,
            transport=transport,
            async_transport=async_transport,
            enable_beta_endpoints=enable_beta_endpoints,
            allow_insecure_download_redirects=allow_insecure_download_redirects,
            expected_v2_version=expected_v2_version,
            timeout=timeout,
            max_retries=max_retries,
            enable_cache=enable_cache,
            cache_ttl=cache_ttl,
            log_requests=log_requests,
            on_request=on_request,
            on_response=on_response,
            on_error=on_error,
            on_event=on_event,
            hook_error_policy=hook_error_policy,
            policies=policies or Policies(),
        )
        self._http = HTTPClient(config)

        # Resource management tracking
        self._closed = False
        self._entered_context = False

        # Initialize services
        self._companies: CompanyService | None = None
        self._persons: PersonService | None = None
        self._lists: ListService | None = None
        self._opportunities: OpportunityService | None = None
        self._tasks: TaskService | None = None
        self._notes: NoteService | None = None
        self._reminders: ReminderService | None = None
        self._webhooks: WebhookService | None = None
        self._interactions: InteractionService | None = None
        self._fields: FieldService | None = None
        self._field_values: FieldValueService | None = None
        self._field_value_changes: FieldValueChangesService | None = None
        self._files: EntityFileService | None = None
        self._relationships: RelationshipStrengthService | None = None
        self._auth: AuthService | None = None
        self._rate_limits: RateLimitService | None = None

    @classmethod
    def from_env(
        cls,
        *,
        env_var: str = _DEFAULT_API_KEY_ENV_VAR,
        load_dotenv: bool = False,
        dotenv_path: str | os.PathLike[str] | None = None,
        dotenv_override: bool = False,
        transport: httpx.BaseTransport | None = None,
        async_transport: httpx.AsyncBaseTransport | None = None,
        policies: Policies | None = None,
        on_event: AnyEventHook | None = None,
        hook_error_policy: Literal["swallow", "raise"] = "swallow",
        **kwargs: Any,
    ) -> Affinity:
        """
        Create a client using an API key from the environment.

        By default, reads `AFFINITY_API_KEY`. For local development, you can optionally
        load a `.env` file (requires `python-dotenv`).
        """
        api_key = _api_key_from_env(
            env_var=env_var,
            load_dotenv=load_dotenv,
            dotenv_path=dotenv_path,
            dotenv_override=dotenv_override,
        )
        return cls(
            api_key=api_key,
            transport=transport,
            async_transport=async_transport,
            policies=policies,
            on_event=on_event,
            hook_error_policy=hook_error_policy,
            **kwargs,
        )

    def __enter__(self) -> Affinity:
        self._entered_context = True
        return self

    def __exit__(self, *args: Any) -> None:
        self.close()

    def close(self) -> None:
        """Close the HTTP client and release resources."""
        if not self._closed:
            self._http.close()
            self._closed = True

    def __del__(self) -> None:
        """Warn if client was not properly closed."""
        if not self._closed and not self._entered_context:
            warnings.warn(
                "Affinity client was not closed. "
                "Use 'with Affinity.from_env() as client:' "
                "or call client.close() when done.",
                ResourceWarning,
                stacklevel=2,
            )
            # Still close to prevent actual resource leaks
            with contextlib.suppress(Exception):
                self.close()

    # =========================================================================
    # Service Properties (lazy initialization)
    # =========================================================================

    @property
    def companies(self) -> CompanyService:
        """Company (organization) operations."""
        if self._companies is None:
            self._companies = CompanyService(self._http)
        return self._companies

    @property
    def persons(self) -> PersonService:
        """Person (contact) operations."""
        if self._persons is None:
            self._persons = PersonService(self._http)
        return self._persons

    @property
    def lists(self) -> ListService:
        """List operations."""
        if self._lists is None:
            self._lists = ListService(self._http)
        return self._lists

    @property
    def opportunities(self) -> OpportunityService:
        """Opportunity operations."""
        if self._opportunities is None:
            self._opportunities = OpportunityService(self._http)
        return self._opportunities

    @property
    def tasks(self) -> TaskService:
        """Long-running task operations (polling, waiting)."""
        if self._tasks is None:
            self._tasks = TaskService(self._http)
        return self._tasks

    @property
    def notes(self) -> NoteService:
        """Note operations."""
        if self._notes is None:
            self._notes = NoteService(self._http)
        return self._notes

    @property
    def reminders(self) -> ReminderService:
        """Reminder operations."""
        if self._reminders is None:
            self._reminders = ReminderService(self._http)
        return self._reminders

    @property
    def webhooks(self) -> WebhookService:
        """Webhook subscription operations."""
        if self._webhooks is None:
            self._webhooks = WebhookService(self._http)
        return self._webhooks

    @property
    def interactions(self) -> InteractionService:
        """Interaction operations."""
        if self._interactions is None:
            self._interactions = InteractionService(self._http)
        return self._interactions

    @property
    def fields(self) -> FieldService:
        """Custom field operations."""
        if self._fields is None:
            self._fields = FieldService(self._http)
        return self._fields

    @property
    def field_values(self) -> FieldValueService:
        """Field value operations."""
        if self._field_values is None:
            self._field_values = FieldValueService(self._http)
        return self._field_values

    @property
    def field_value_changes(self) -> FieldValueChangesService:
        """Field value change history queries."""
        if self._field_value_changes is None:
            self._field_value_changes = FieldValueChangesService(self._http)
        return self._field_value_changes

    @property
    def files(self) -> EntityFileService:
        """Entity file operations."""
        if self._files is None:
            self._files = EntityFileService(self._http)
        return self._files

    @property
    def relationships(self) -> RelationshipStrengthService:
        """Relationship strength queries."""
        if self._relationships is None:
            self._relationships = RelationshipStrengthService(self._http)
        return self._relationships

    @property
    def auth(self) -> AuthService:
        """Authentication info."""
        if self._auth is None:
            self._auth = AuthService(self._http)
        return self._auth

    @property
    def rate_limits(self) -> RateLimitService:
        """Unified rate limit information (version-agnostic)."""
        if self._rate_limits is None:
            self._rate_limits = RateLimitService(self._http)
        return self._rate_limits

    # =========================================================================
    # Utility Methods
    # =========================================================================

    def clear_cache(self) -> None:
        """Clear the response cache."""
        if self._http.cache:
            self._http.cache.clear()

    def whoami(self) -> WhoAmI:
        """Convenience wrapper for `client.auth.whoami()`."""
        return self.auth.whoami()

auth: AuthService property

Authentication info.

companies: CompanyService property

Company (organization) operations.

field_value_changes: FieldValueChangesService property

Field value change history queries.

field_values: FieldValueService property

Field value operations.

fields: FieldService property

Custom field operations.

files: EntityFileService property

Entity file operations.

interactions: InteractionService property

Interaction operations.

lists: ListService property

List operations.

notes: NoteService property

Note operations.

opportunities: OpportunityService property

Opportunity operations.

persons: PersonService property

Person (contact) operations.

rate_limits: RateLimitService property

Unified rate limit information (version-agnostic).

relationships: RelationshipStrengthService property

Relationship strength queries.

reminders: ReminderService property

Reminder operations.

tasks: TaskService property

Long-running task operations (polling, waiting).

webhooks: WebhookService property

Webhook subscription operations.

__del__() -> None

Warn if client was not properly closed.

Source code in affinity/client.py 
315
316
317
318
319
320
321
322
323
324
325
326
327
def __del__(self) -> None:
    """Warn if client was not properly closed."""
    if not self._closed and not self._entered_context:
        warnings.warn(
            "Affinity client was not closed. "
            "Use 'with Affinity.from_env() as client:' "
            "or call client.close() when done.",
            ResourceWarning,
            stacklevel=2,
        )
        # Still close to prevent actual resource leaks
        with contextlib.suppress(Exception):
            self.close()

__init__(api_key: str, *, v1_base_url: str = V1_BASE_URL, v2_base_url: str = V2_BASE_URL, v1_auth_mode: Literal['bearer', 'basic'] = 'bearer', transport: httpx.BaseTransport | None = None, async_transport: httpx.AsyncBaseTransport | None = None, enable_beta_endpoints: bool = False, allow_insecure_download_redirects: bool = False, expected_v2_version: str | None = None, timeout: float = 30.0, max_retries: int = 3, enable_cache: bool = False, cache_ttl: float = 300.0, log_requests: bool = False, on_request: RequestHook | None = None, on_response: ResponseHook | None = None, on_error: ErrorHook | None = None, on_event: AnyEventHook | None = None, hook_error_policy: Literal['swallow', 'raise'] = 'swallow', policies: Policies | None = None)

Initialize the Affinity client.

Parameters:

Name Type Description Default
api_key str

Your Affinity API key

 required
v1_base_url str

V1 API base URL (default: https://api.affinity.co)

 V1_BASE_URL
v2_base_url str

V2 API base URL (default: https://api.affinity.co/v2)

 V2_BASE_URL
v1_auth_mode Literal['bearer', 'basic']

Auth mode for V1 API ("bearer" or "basic")

 'bearer'
transport BaseTransport | None

Optional httpx transport (advanced; useful for mocking in tests)

 None
async_transport AsyncBaseTransport | None

Optional async httpx transport (advanced; useful for mocking in tests)

 None
enable_beta_endpoints bool

Enable beta V2 endpoints

 False
allow_insecure_download_redirects bool

Allow http:// redirects for file downloads. Not recommended; prefer HTTPS-only downloads.

 False
expected_v2_version str | None

Expected V2 API version for diagnostics (e.g., "2024-01-01"). Used to detect version compatibility issues. See TR-015.

 None
timeout float

Request timeout in seconds

 30.0
max_retries int

Maximum retries for rate-limited requests

 3
enable_cache bool

Enable response caching for field metadata

 False
cache_ttl float

Cache TTL in seconds

 300.0
log_requests bool

Log all HTTP requests (for debugging)

 False
on_request RequestHook | None

Hook called before each request (DX-008)

 None
on_response ResponseHook | None

Hook called after each response (DX-008)

 None
on_error ErrorHook | None

Hook called when a request raises (DX-008)

 None
on_event AnyEventHook | None

Event hook called for request/response lifecycle events (DX-008)

 None
hook_error_policy Literal['swallow', 'raise']

What to do if hooks raise ("swallow" or "raise")

 'swallow'
policies Policies | None

Client policies (e.g., disable writes)

 None
Source code in affinity/client.py 
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
def __init__(
    self,
    api_key: str,
    *,
    v1_base_url: str = V1_BASE_URL,
    v2_base_url: str = V2_BASE_URL,
    v1_auth_mode: Literal["bearer", "basic"] = "bearer",
    transport: httpx.BaseTransport | None = None,
    async_transport: httpx.AsyncBaseTransport | None = None,
    enable_beta_endpoints: bool = False,
    allow_insecure_download_redirects: bool = False,
    expected_v2_version: str | None = None,
    timeout: float = 30.0,
    max_retries: int = 3,
    enable_cache: bool = False,
    cache_ttl: float = 300.0,
    log_requests: bool = False,
    on_request: RequestHook | None = None,
    on_response: ResponseHook | None = None,
    on_error: ErrorHook | None = None,
    on_event: AnyEventHook | None = None,
    hook_error_policy: Literal["swallow", "raise"] = "swallow",
    policies: Policies | None = None,
):
    """
    Initialize the Affinity client.

    Args:
        api_key: Your Affinity API key
        v1_base_url: V1 API base URL (default: https://api.affinity.co)
        v2_base_url: V2 API base URL (default: https://api.affinity.co/v2)
        v1_auth_mode: Auth mode for V1 API ("bearer" or "basic")
        transport: Optional `httpx` transport (advanced; useful for mocking in tests)
        async_transport: Optional async `httpx` transport (advanced; useful for mocking in
            tests)
        enable_beta_endpoints: Enable beta V2 endpoints
        allow_insecure_download_redirects: Allow `http://` redirects for file downloads.
            Not recommended; prefer HTTPS-only downloads.
        expected_v2_version: Expected V2 API version for diagnostics (e.g.,
            "2024-01-01"). Used to detect version compatibility issues.
            See TR-015.
        timeout: Request timeout in seconds
        max_retries: Maximum retries for rate-limited requests
        enable_cache: Enable response caching for field metadata
        cache_ttl: Cache TTL in seconds
        log_requests: Log all HTTP requests (for debugging)
        on_request: Hook called before each request (DX-008)
        on_response: Hook called after each response (DX-008)
        on_error: Hook called when a request raises (DX-008)
        on_event: Event hook called for request/response lifecycle events (DX-008)
        hook_error_policy: What to do if hooks raise ("swallow" or "raise")
        policies: Client policies (e.g., disable writes)
    """
    config = ClientConfig(
        api_key=api_key,
        v1_base_url=v1_base_url,
        v2_base_url=v2_base_url,
        v1_auth_mode=v1_auth_mode,
        transport=transport,
        async_transport=async_transport,
        enable_beta_endpoints=enable_beta_endpoints,
        allow_insecure_download_redirects=allow_insecure_download_redirects,
        expected_v2_version=expected_v2_version,
        timeout=timeout,
        max_retries=max_retries,
        enable_cache=enable_cache,
        cache_ttl=cache_ttl,
        log_requests=log_requests,
        on_request=on_request,
        on_response=on_response,
        on_error=on_error,
        on_event=on_event,
        hook_error_policy=hook_error_policy,
        policies=policies or Policies(),
    )
    self._http = HTTPClient(config)

    # Resource management tracking
    self._closed = False
    self._entered_context = False

    # Initialize services
    self._companies: CompanyService | None = None
    self._persons: PersonService | None = None
    self._lists: ListService | None = None
    self._opportunities: OpportunityService | None = None
    self._tasks: TaskService | None = None
    self._notes: NoteService | None = None
    self._reminders: ReminderService | None = None
    self._webhooks: WebhookService | None = None
    self._interactions: InteractionService | None = None
    self._fields: FieldService | None = None
    self._field_values: FieldValueService | None = None
    self._field_value_changes: FieldValueChangesService | None = None
    self._files: EntityFileService | None = None
    self._relationships: RelationshipStrengthService | None = None
    self._auth: AuthService | None = None
    self._rate_limits: RateLimitService | None = None

clear_cache() -> None

Clear the response cache.

Source code in affinity/client.py 
449
450
451
452
def clear_cache(self) -> None:
    """Clear the response cache."""
    if self._http.cache:
        self._http.cache.clear()

close() -> None

Close the HTTP client and release resources.

Source code in affinity/client.py 
309
310
311
312
313
def close(self) -> None:
    """Close the HTTP client and release resources."""
    if not self._closed:
        self._http.close()
        self._closed = True

from_env(*, env_var: str = _DEFAULT_API_KEY_ENV_VAR, load_dotenv: bool = False, dotenv_path: str | os.PathLike[str] | None = None, dotenv_override: bool = False, transport: httpx.BaseTransport | None = None, async_transport: httpx.AsyncBaseTransport | None = None, policies: Policies | None = None, on_event: AnyEventHook | None = None, hook_error_policy: Literal['swallow', 'raise'] = 'swallow', **kwargs: Any) -> Affinity classmethod

Create a client using an API key from the environment.

By default, reads AFFINITY_API_KEY. For local development, you can optionally load a .env file (requires python-dotenv).

Source code in affinity/client.py 
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
@classmethod
def from_env(
    cls,
    *,
    env_var: str = _DEFAULT_API_KEY_ENV_VAR,
    load_dotenv: bool = False,
    dotenv_path: str | os.PathLike[str] | None = None,
    dotenv_override: bool = False,
    transport: httpx.BaseTransport | None = None,
    async_transport: httpx.AsyncBaseTransport | None = None,
    policies: Policies | None = None,
    on_event: AnyEventHook | None = None,
    hook_error_policy: Literal["swallow", "raise"] = "swallow",
    **kwargs: Any,
) -> Affinity:
    """
    Create a client using an API key from the environment.

    By default, reads `AFFINITY_API_KEY`. For local development, you can optionally
    load a `.env` file (requires `python-dotenv`).
    """
    api_key = _api_key_from_env(
        env_var=env_var,
        load_dotenv=load_dotenv,
        dotenv_path=dotenv_path,
        dotenv_override=dotenv_override,
    )
    return cls(
        api_key=api_key,
        transport=transport,
        async_transport=async_transport,
        policies=policies,
        on_event=on_event,
        hook_error_policy=hook_error_policy,
        **kwargs,
    )

whoami() -> WhoAmI

Convenience wrapper for client.auth.whoami().

Source code in affinity/client.py 
454
455
456
def whoami(self) -> WhoAmI:
    """Convenience wrapper for `client.auth.whoami()`."""
    return self.auth.whoami()

AsyncAffinity

Asynchronous Affinity API client.

Same interface as Affinity but with async/await support.

Example 
async with AsyncAffinity(api_key="your-key") as client:
    async for company in client.companies.all():
        print(company.name)
Source code in affinity/client.py 
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
class AsyncAffinity:
    """
    Asynchronous Affinity API client.

    Same interface as Affinity but with async/await support.

    Example:
        ```python
        async with AsyncAffinity(api_key="your-key") as client:
            async for company in client.companies.all():
                print(company.name)
        ```
    """

    def __init__(
        self,
        api_key: str,
        *,
        v1_base_url: str = V1_BASE_URL,
        v2_base_url: str = V2_BASE_URL,
        v1_auth_mode: Literal["bearer", "basic"] = "bearer",
        transport: httpx.BaseTransport | None = None,
        async_transport: httpx.AsyncBaseTransport | None = None,
        enable_beta_endpoints: bool = False,
        allow_insecure_download_redirects: bool = False,
        expected_v2_version: str | None = None,
        timeout: float = 30.0,
        max_retries: int = 3,
        enable_cache: bool = False,
        cache_ttl: float = 300.0,
        log_requests: bool = False,
        on_request: RequestHook | None = None,
        on_response: ResponseHook | None = None,
        on_error: ErrorHook | None = None,
        on_event: AnyEventHook | None = None,
        hook_error_policy: Literal["swallow", "raise"] = "swallow",
        policies: Policies | None = None,
    ):
        """
        Initialize the async Affinity client.

        Args:
            api_key: Your Affinity API key
            v1_base_url: V1 API base URL (default: https://api.affinity.co)
            v2_base_url: V2 API base URL (default: https://api.affinity.co/v2)
            v1_auth_mode: Auth mode for V1 API ("bearer" or "basic")
            transport: Optional `httpx` transport (advanced; useful for mocking in tests)
            async_transport: Optional async `httpx` transport (advanced; useful for mocking in
                tests)
            enable_beta_endpoints: Enable beta V2 endpoints
            allow_insecure_download_redirects: Allow `http://` redirects for file downloads.
                Not recommended; prefer HTTPS-only downloads.
            expected_v2_version: Expected V2 API version for diagnostics (e.g.,
                "2024-01-01"). Used to detect version compatibility issues.
                See TR-015.
            timeout: Request timeout in seconds
            max_retries: Maximum retries for rate-limited requests
            enable_cache: Enable response caching for field metadata
            cache_ttl: Cache TTL in seconds
            log_requests: Log all HTTP requests (for debugging)
            on_request: Hook called before each request (DX-008)
            on_response: Hook called after each response (DX-008)
            on_error: Hook called when a request raises (DX-008)
            on_event: Event hook called for request/response lifecycle events (DX-008)
            hook_error_policy: What to do if hooks raise ("swallow" or "raise")
        """
        config = ClientConfig(
            api_key=api_key,
            v1_base_url=v1_base_url,
            v2_base_url=v2_base_url,
            v1_auth_mode=v1_auth_mode,
            transport=transport,
            async_transport=async_transport,
            enable_beta_endpoints=enable_beta_endpoints,
            allow_insecure_download_redirects=allow_insecure_download_redirects,
            expected_v2_version=expected_v2_version,
            timeout=timeout,
            max_retries=max_retries,
            enable_cache=enable_cache,
            cache_ttl=cache_ttl,
            log_requests=log_requests,
            on_request=on_request,
            on_response=on_response,
            on_error=on_error,
            on_event=on_event,
            hook_error_policy=hook_error_policy,
            policies=policies or Policies(),
        )
        self._http = AsyncHTTPClient(config)

        # Resource management tracking
        self._closed = False
        self._entered_context = False

        self._companies: AsyncCompanyService | None = None
        self._persons: AsyncPersonService | None = None
        self._opportunities: AsyncOpportunityService | None = None
        self._lists: AsyncListService | None = None
        self._tasks: AsyncTaskService | None = None
        self._notes: AsyncNoteService | None = None
        self._reminders: AsyncReminderService | None = None
        self._webhooks: AsyncWebhookService | None = None
        self._interactions: AsyncInteractionService | None = None
        self._fields: AsyncFieldService | None = None
        self._field_values: AsyncFieldValueService | None = None
        self._field_value_changes: AsyncFieldValueChangesService | None = None
        self._files: AsyncEntityFileService | None = None
        self._relationships: AsyncRelationshipStrengthService | None = None
        self._auth: AsyncAuthService | None = None
        self._rate_limits: AsyncRateLimitService | None = None

    @classmethod
    def from_env(
        cls,
        *,
        env_var: str = _DEFAULT_API_KEY_ENV_VAR,
        load_dotenv: bool = False,
        dotenv_path: str | os.PathLike[str] | None = None,
        dotenv_override: bool = False,
        transport: httpx.BaseTransport | None = None,
        async_transport: httpx.AsyncBaseTransport | None = None,
        policies: Policies | None = None,
        on_event: AnyEventHook | None = None,
        hook_error_policy: Literal["swallow", "raise"] = "swallow",
        **kwargs: Any,
    ) -> AsyncAffinity:
        """
        Create an async client using an API key from the environment.

        By default, reads `AFFINITY_API_KEY`. For local development, you can optionally
        load a `.env` file (requires `python-dotenv`).
        """
        api_key = _api_key_from_env(
            env_var=env_var,
            load_dotenv=load_dotenv,
            dotenv_path=dotenv_path,
            dotenv_override=dotenv_override,
        )
        return cls(
            api_key=api_key,
            transport=transport,
            async_transport=async_transport,
            policies=policies,
            on_event=on_event,
            hook_error_policy=hook_error_policy,
            **kwargs,
        )

    @property
    def companies(self) -> AsyncCompanyService:
        """Company (organization) operations."""
        if self._companies is None:
            self._companies = AsyncCompanyService(self._http)
        return self._companies

    @property
    def persons(self) -> AsyncPersonService:
        """Person (contact) operations."""
        if self._persons is None:
            self._persons = AsyncPersonService(self._http)
        return self._persons

    @property
    def opportunities(self) -> AsyncOpportunityService:
        """Opportunity operations."""
        if self._opportunities is None:
            self._opportunities = AsyncOpportunityService(self._http)
        return self._opportunities

    @property
    def lists(self) -> AsyncListService:
        """List and list entry operations."""
        if self._lists is None:
            self._lists = AsyncListService(self._http)
        return self._lists

    @property
    def tasks(self) -> AsyncTaskService:
        """Long-running task operations (polling, waiting)."""
        if self._tasks is None:
            self._tasks = AsyncTaskService(self._http)
        return self._tasks

    @property
    def notes(self) -> AsyncNoteService:
        """Note operations."""
        if self._notes is None:
            self._notes = AsyncNoteService(self._http)
        return self._notes

    @property
    def reminders(self) -> AsyncReminderService:
        """Reminder operations."""
        if self._reminders is None:
            self._reminders = AsyncReminderService(self._http)
        return self._reminders

    @property
    def webhooks(self) -> AsyncWebhookService:
        """Webhook subscription operations."""
        if self._webhooks is None:
            self._webhooks = AsyncWebhookService(self._http)
        return self._webhooks

    @property
    def interactions(self) -> AsyncInteractionService:
        """Interaction operations."""
        if self._interactions is None:
            self._interactions = AsyncInteractionService(self._http)
        return self._interactions

    @property
    def fields(self) -> AsyncFieldService:
        """Custom field operations."""
        if self._fields is None:
            self._fields = AsyncFieldService(self._http)
        return self._fields

    @property
    def field_values(self) -> AsyncFieldValueService:
        """Field value operations."""
        if self._field_values is None:
            self._field_values = AsyncFieldValueService(self._http)
        return self._field_values

    @property
    def field_value_changes(self) -> AsyncFieldValueChangesService:
        """Field value change history queries."""
        if self._field_value_changes is None:
            self._field_value_changes = AsyncFieldValueChangesService(self._http)
        return self._field_value_changes

    @property
    def files(self) -> AsyncEntityFileService:
        """Entity file operations."""
        if self._files is None:
            self._files = AsyncEntityFileService(self._http)
        return self._files

    @property
    def relationships(self) -> AsyncRelationshipStrengthService:
        """Relationship strength queries."""
        if self._relationships is None:
            self._relationships = AsyncRelationshipStrengthService(self._http)
        return self._relationships

    @property
    def auth(self) -> AsyncAuthService:
        """Authentication info."""
        if self._auth is None:
            self._auth = AsyncAuthService(self._http)
        return self._auth

    @property
    def rate_limits(self) -> AsyncRateLimitService:
        """Unified rate limit information (version-agnostic)."""
        if self._rate_limits is None:
            self._rate_limits = AsyncRateLimitService(self._http)
        return self._rate_limits

    async def __aenter__(self) -> AsyncAffinity:
        """Enter an async context and return this client."""
        self._entered_context = True
        return self

    async def __aexit__(self, *args: Any) -> None:
        """Exit the async context and close the underlying HTTP client."""
        await self.close()

    async def close(self) -> None:
        """Close the HTTP client."""
        if not self._closed:
            await self._http.close()
            self._closed = True

    def __del__(self) -> None:
        """Warn if client was not properly closed."""
        if not self._closed and not self._entered_context:
            warnings.warn(
                "AsyncAffinity client was not closed. "
                "Use 'async with AsyncAffinity.from_env() as client:' "
                "or call await client.close() when done.",
                ResourceWarning,
                stacklevel=2,
            )
            # Schedule close if loop is running; otherwise silently skip
            # (can't await in __del__, and sync close would block)
            # Use call_soon_threadsafe for thread-safety in multi-threaded loops
            try:
                loop = asyncio.get_running_loop()
                loop.call_soon_threadsafe(lambda: asyncio.create_task(self._http.close()))
            except RuntimeError:
                pass  # No running loop - skip async cleanup

    def clear_cache(self) -> None:
        """Clear the response cache."""
        if self._http.cache:
            self._http.cache.clear()

    async def whoami(self) -> WhoAmI:
        """Convenience wrapper for `client.auth.whoami()`."""
        return await self.auth.whoami()

auth: AsyncAuthService property

Authentication info.

companies: AsyncCompanyService property

Company (organization) operations.

field_value_changes: AsyncFieldValueChangesService property

Field value change history queries.

field_values: AsyncFieldValueService property

Field value operations.

fields: AsyncFieldService property

Custom field operations.

files: AsyncEntityFileService property

Entity file operations.

interactions: AsyncInteractionService property

Interaction operations.

lists: AsyncListService property

List and list entry operations.

notes: AsyncNoteService property

Note operations.

opportunities: AsyncOpportunityService property

Opportunity operations.

persons: AsyncPersonService property

Person (contact) operations.

rate_limits: AsyncRateLimitService property

Unified rate limit information (version-agnostic).

relationships: AsyncRelationshipStrengthService property

Relationship strength queries.

reminders: AsyncReminderService property

Reminder operations.

tasks: AsyncTaskService property

Long-running task operations (polling, waiting).

webhooks: AsyncWebhookService property

Webhook subscription operations.

__aenter__() -> AsyncAffinity async

Enter an async context and return this client.

Source code in affinity/client.py 
728
729
730
731
async def __aenter__(self) -> AsyncAffinity:
    """Enter an async context and return this client."""
    self._entered_context = True
    return self

__aexit__(*args: Any) -> None async

Exit the async context and close the underlying HTTP client.

Source code in affinity/client.py 
733
734
735
async def __aexit__(self, *args: Any) -> None:
    """Exit the async context and close the underlying HTTP client."""
    await self.close()

__del__() -> None

Warn if client was not properly closed.

Source code in affinity/client.py 
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
def __del__(self) -> None:
    """Warn if client was not properly closed."""
    if not self._closed and not self._entered_context:
        warnings.warn(
            "AsyncAffinity client was not closed. "
            "Use 'async with AsyncAffinity.from_env() as client:' "
            "or call await client.close() when done.",
            ResourceWarning,
            stacklevel=2,
        )
        # Schedule close if loop is running; otherwise silently skip
        # (can't await in __del__, and sync close would block)
        # Use call_soon_threadsafe for thread-safety in multi-threaded loops
        try:
            loop = asyncio.get_running_loop()
            loop.call_soon_threadsafe(lambda: asyncio.create_task(self._http.close()))
        except RuntimeError:
            pass  # No running loop - skip async cleanup

__init__(api_key: str, *, v1_base_url: str = V1_BASE_URL, v2_base_url: str = V2_BASE_URL, v1_auth_mode: Literal['bearer', 'basic'] = 'bearer', transport: httpx.BaseTransport | None = None, async_transport: httpx.AsyncBaseTransport | None = None, enable_beta_endpoints: bool = False, allow_insecure_download_redirects: bool = False, expected_v2_version: str | None = None, timeout: float = 30.0, max_retries: int = 3, enable_cache: bool = False, cache_ttl: float = 300.0, log_requests: bool = False, on_request: RequestHook | None = None, on_response: ResponseHook | None = None, on_error: ErrorHook | None = None, on_event: AnyEventHook | None = None, hook_error_policy: Literal['swallow', 'raise'] = 'swallow', policies: Policies | None = None)

Initialize the async Affinity client.

Parameters:

Name Type Description Default
api_key str

Your Affinity API key

 required
v1_base_url str

V1 API base URL (default: https://api.affinity.co)

 V1_BASE_URL
v2_base_url str

V2 API base URL (default: https://api.affinity.co/v2)

 V2_BASE_URL
v1_auth_mode Literal['bearer', 'basic']

Auth mode for V1 API ("bearer" or "basic")

 'bearer'
transport BaseTransport | None

Optional httpx transport (advanced; useful for mocking in tests)

 None
async_transport AsyncBaseTransport | None

Optional async httpx transport (advanced; useful for mocking in tests)

 None
enable_beta_endpoints bool

Enable beta V2 endpoints

 False
allow_insecure_download_redirects bool

Allow http:// redirects for file downloads. Not recommended; prefer HTTPS-only downloads.

 False
expected_v2_version str | None

Expected V2 API version for diagnostics (e.g., "2024-01-01"). Used to detect version compatibility issues. See TR-015.

 None
timeout float

Request timeout in seconds

 30.0
max_retries int

Maximum retries for rate-limited requests

 3
enable_cache bool

Enable response caching for field metadata

 False
cache_ttl float

Cache TTL in seconds

 300.0
log_requests bool

Log all HTTP requests (for debugging)

 False
on_request RequestHook | None

Hook called before each request (DX-008)

 None
on_response ResponseHook | None

Hook called after each response (DX-008)

 None
on_error ErrorHook | None

Hook called when a request raises (DX-008)

 None
on_event AnyEventHook | None

Event hook called for request/response lifecycle events (DX-008)

 None
hook_error_policy Literal['swallow', 'raise']

What to do if hooks raise ("swallow" or "raise")

 'swallow'
Source code in affinity/client.py 
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
def __init__(
    self,
    api_key: str,
    *,
    v1_base_url: str = V1_BASE_URL,
    v2_base_url: str = V2_BASE_URL,
    v1_auth_mode: Literal["bearer", "basic"] = "bearer",
    transport: httpx.BaseTransport | None = None,
    async_transport: httpx.AsyncBaseTransport | None = None,
    enable_beta_endpoints: bool = False,
    allow_insecure_download_redirects: bool = False,
    expected_v2_version: str | None = None,
    timeout: float = 30.0,
    max_retries: int = 3,
    enable_cache: bool = False,
    cache_ttl: float = 300.0,
    log_requests: bool = False,
    on_request: RequestHook | None = None,
    on_response: ResponseHook | None = None,
    on_error: ErrorHook | None = None,
    on_event: AnyEventHook | None = None,
    hook_error_policy: Literal["swallow", "raise"] = "swallow",
    policies: Policies | None = None,
):
    """
    Initialize the async Affinity client.

    Args:
        api_key: Your Affinity API key
        v1_base_url: V1 API base URL (default: https://api.affinity.co)
        v2_base_url: V2 API base URL (default: https://api.affinity.co/v2)
        v1_auth_mode: Auth mode for V1 API ("bearer" or "basic")
        transport: Optional `httpx` transport (advanced; useful for mocking in tests)
        async_transport: Optional async `httpx` transport (advanced; useful for mocking in
            tests)
        enable_beta_endpoints: Enable beta V2 endpoints
        allow_insecure_download_redirects: Allow `http://` redirects for file downloads.
            Not recommended; prefer HTTPS-only downloads.
        expected_v2_version: Expected V2 API version for diagnostics (e.g.,
            "2024-01-01"). Used to detect version compatibility issues.
            See TR-015.
        timeout: Request timeout in seconds
        max_retries: Maximum retries for rate-limited requests
        enable_cache: Enable response caching for field metadata
        cache_ttl: Cache TTL in seconds
        log_requests: Log all HTTP requests (for debugging)
        on_request: Hook called before each request (DX-008)
        on_response: Hook called after each response (DX-008)
        on_error: Hook called when a request raises (DX-008)
        on_event: Event hook called for request/response lifecycle events (DX-008)
        hook_error_policy: What to do if hooks raise ("swallow" or "raise")
    """
    config = ClientConfig(
        api_key=api_key,
        v1_base_url=v1_base_url,
        v2_base_url=v2_base_url,
        v1_auth_mode=v1_auth_mode,
        transport=transport,
        async_transport=async_transport,
        enable_beta_endpoints=enable_beta_endpoints,
        allow_insecure_download_redirects=allow_insecure_download_redirects,
        expected_v2_version=expected_v2_version,
        timeout=timeout,
        max_retries=max_retries,
        enable_cache=enable_cache,
        cache_ttl=cache_ttl,
        log_requests=log_requests,
        on_request=on_request,
        on_response=on_response,
        on_error=on_error,
        on_event=on_event,
        hook_error_policy=hook_error_policy,
        policies=policies or Policies(),
    )
    self._http = AsyncHTTPClient(config)

    # Resource management tracking
    self._closed = False
    self._entered_context = False

    self._companies: AsyncCompanyService | None = None
    self._persons: AsyncPersonService | None = None
    self._opportunities: AsyncOpportunityService | None = None
    self._lists: AsyncListService | None = None
    self._tasks: AsyncTaskService | None = None
    self._notes: AsyncNoteService | None = None
    self._reminders: AsyncReminderService | None = None
    self._webhooks: AsyncWebhookService | None = None
    self._interactions: AsyncInteractionService | None = None
    self._fields: AsyncFieldService | None = None
    self._field_values: AsyncFieldValueService | None = None
    self._field_value_changes: AsyncFieldValueChangesService | None = None
    self._files: AsyncEntityFileService | None = None
    self._relationships: AsyncRelationshipStrengthService | None = None
    self._auth: AsyncAuthService | None = None
    self._rate_limits: AsyncRateLimitService | None = None

clear_cache() -> None

Clear the response cache.

Source code in affinity/client.py 
762
763
764
765
def clear_cache(self) -> None:
    """Clear the response cache."""
    if self._http.cache:
        self._http.cache.clear()

close() -> None async

Close the HTTP client.

Source code in affinity/client.py 
737
738
739
740
741
async def close(self) -> None:
    """Close the HTTP client."""
    if not self._closed:
        await self._http.close()
        self._closed = True

from_env(*, env_var: str = _DEFAULT_API_KEY_ENV_VAR, load_dotenv: bool = False, dotenv_path: str | os.PathLike[str] | None = None, dotenv_override: bool = False, transport: httpx.BaseTransport | None = None, async_transport: httpx.AsyncBaseTransport | None = None, policies: Policies | None = None, on_event: AnyEventHook | None = None, hook_error_policy: Literal['swallow', 'raise'] = 'swallow', **kwargs: Any) -> AsyncAffinity classmethod

Create an async client using an API key from the environment.

By default, reads AFFINITY_API_KEY. For local development, you can optionally load a .env file (requires python-dotenv).

Source code in affinity/client.py 
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
@classmethod
def from_env(
    cls,
    *,
    env_var: str = _DEFAULT_API_KEY_ENV_VAR,
    load_dotenv: bool = False,
    dotenv_path: str | os.PathLike[str] | None = None,
    dotenv_override: bool = False,
    transport: httpx.BaseTransport | None = None,
    async_transport: httpx.AsyncBaseTransport | None = None,
    policies: Policies | None = None,
    on_event: AnyEventHook | None = None,
    hook_error_policy: Literal["swallow", "raise"] = "swallow",
    **kwargs: Any,
) -> AsyncAffinity:
    """
    Create an async client using an API key from the environment.

    By default, reads `AFFINITY_API_KEY`. For local development, you can optionally
    load a `.env` file (requires `python-dotenv`).
    """
    api_key = _api_key_from_env(
        env_var=env_var,
        load_dotenv=load_dotenv,
        dotenv_path=dotenv_path,
        dotenv_override=dotenv_override,
    )
    return cls(
        api_key=api_key,
        transport=transport,
        async_transport=async_transport,
        policies=policies,
        on_event=on_event,
        hook_error_policy=hook_error_policy,
        **kwargs,
    )

whoami() -> WhoAmI async

Convenience wrapper for client.auth.whoami().

Source code in affinity/client.py 
767
768
769
async def whoami(self) -> WhoAmI:
    """Convenience wrapper for `client.auth.whoami()`."""
    return await self.auth.whoami()