dlt-source-affinity 0.1.16

A DLT source for the Affinity CRM

---

description: dlt source for affinity.co keywords: [Affinity API, affinity.co, CRM]

dlt-source-affinity

DLT source for Affinity.

If you don't know DLT but stumbled across this when trying to search if you can get your data out of Affinity somehow: this will do it - it basically allows you to pull mostly any (except some enriched) data out of your Affinity instance and into a different target system (Snowflake, Postgres, etc.) that is supported by DLT.

Usage

Create a .dlt/secrets.toml with your API key:

affinity_api_key="<YOUR_API_KEY>"

and then run the default source with optional list references:

from dlt_source_affinity import ListReference, source as affinity_source

pipeline = dlt.pipeline(
   pipeline_name="affinity_pipeline",
   destination="duckdb",
   dev_mode=True,
)
affinity_data = affinity_source(
   # By default the data source loads:
   # - organizations
   # - persons
   # - lists
   # - opportunities
   # - notes
   # And then we can optionally pass an arbitrary number of lists and list views:
   list_refs=[
      # Loads a list with ID 123,
      # e.g. https://<your-subdomain>.affinity.co/lists/123/
      ListReference(123),
      # Loads a view with ID 456 in list 123,
      # e.g. https://<your-subdomain>.affinity.co/lists/123/views/456-all-organizations
      ListReference(123, 456),
   ]
)
pipeline.run(affinity_data)

Resources

Resources that can be loaded using this verified source are:

Name	Description	API version	Permissions needed
companies	The stored companies	V2	Requires the "Export All Organizations directory" permission.
persons	The stored persons	V2	Requires the "Export All People directory" permission.
opportunities	The stored opportunities	V2	Requires the "Export data from Lists" permission.
lists	A given list and/or a saved view of a list	V2	Requires the "Export data from Lists" permission.
notes	Notes attached to companies, persons, opportunities	Legacy	n/a

V1 vs V2

There are two versions of the Affinity API:

1. Legacy which is available for all plans.
2. V2 which is only available for customers with an enterprise plan.

This verified source makes use of both API endpoints. The authentication credentials for both APIs are the same, however, they differ in their authentication behavior.

Initialize the pipeline

dlt init affinity duckdb

Here, we chose duckdb as the destination. Alternatively, you can also choose redshift, bigquery, or any of the other destinations.

Add credentials

1. You'll need to obtain your API key and configure the pipeline with it.

Development

This project is using devenv.

Run the sample

AFFINITY_API_KEY=[...] python affinity_pipeline.py

Regenerate V2 model

Run

generate-model

🚀 Development Workflow

1. Make changes to your code
2. Format code with format before committing
3. Commit changes - pre-commit hooks will run automatically
4. Push to GitHub - CI will run tests on multiple platforms
5. Create release by pushing a tag (format: vX.X.X)

📦 Publishing

Publishing to PyPI is fully automated:

1. Create a new tag: git tag v1.0.0
2. Push the tag: git push origin v1.0.0
3. GitHub Actions will automatically build and publish to PyPI

The project uses trusted publishing, so no API keys are required.