Affinity integration

Overview

Affinity is a relationship intelligence CRM. This tool provides CRUD operations for organizations, persons, lists, and list entries via the Affinity API. It supports creating, reading, updating, and deleting records, as well as searching and paginating through results.

Node Type

Action — processes input items and produces output

Input / Output

Direction	Port(s)
Input	Input
Output	Output, Error

Credentials

This tool requires Affinity API credentials. See the Credentials Guide for setup instructions.

Resources

Resource	Value
List	list
List Entry	listEntry
Organization	organization
Person	person

Operations

Which operations are available depends on the selected resource — see the parameter subsections below. Lists are read-only: they offer get and getAll only.

Operation	Value	Description
Create	create	Create a list entry, organization or person.
Delete	delete	Delete a list entry, organization or person.
Get	get	Get a single record.
Get Many	getAll	Get many records.
Update	update	Update an organization or person.

Parameters

List: Get

Parameter	Type	Required	Default	Description
List ID	string	Yes	—	The unique ID of the list object to be retrieved.

List: Get Many

Parameter	Type	Required	Default	Description
Return All	boolean	No	false	Whether to return all results or only up to a given limit.
Limit	number	No	5	Max number of results to return. (shown when Return All is false)

List Entry: Create

Parameter	Type	Required	Default	Description
List ID	string	Yes	—	The unique ID of the list to add the entry to. To find list IDs, use the List > Get Many operation.
Entity ID	string	Yes	—	The unique ID of the entity (person, organization, or opportunity) to add to this list.
Additional Fields	collection	No	{}	Optional fields sent with the new list entry.
— Creator ID	string	No	—	The ID of a Person resource who should be recorded as adding the entry to the list. Must be a person who can access Affinity. If not provided the creator defaults to the owner of the API key.

List Entry: Delete

Parameter	Type	Required	Default	Description
List ID	string	Yes	—	The unique ID of the list that contains the specified list entry. To find list IDs, use the List > Get Many operation.
List Entry ID	string	Yes	—	The unique ID of the list entry object to be deleted.

List Entry: Get

Parameter	Type	Required	Default	Description
List ID	string	Yes	—	The unique ID of the list that contains the specified list entry. To find list IDs, use the List > Get Many operation.
List Entry ID	string	Yes	—	The unique ID of the list entry object to be retrieved.

List Entry: Get Many

Parameter	Type	Required	Default	Description
List ID	string	No	—	The unique ID of the list whose list entries are to be retrieved. To find list IDs, use the List > Get Many operation.
Return All	boolean	No	false	Whether to return all results or only up to a given limit.
Limit	number	No	5	Max number of results to return. (shown when Return All is false)

Organization: Create

Parameter	Type	Required	Default	Description
Name	string	Yes	—	The name of the organization.
Domain	string	Yes	—	The domain name of the organization.
Additional Fields	collection	No	{}	Optional fields sent with the new organization.
— Person IDs	string	No	—	Comma-separated IDs of persons to associate with this organization. Find person IDs via Person > Get Many.

Organization: Delete

Parameter	Type	Required	Default	Description
Organization ID	string	Yes	—	Unique identifier for the organization.

Organization: Get

Parameter	Type	Required	Default	Description
Organization ID	string	Yes	—	Unique identifier for the organization.
Options	collection	No	{}	Extra settings applied to the lookup.
— With Interaction Dates	boolean	No	false	Whether interaction dates will be present on the returned resources.

Organization: Get Many

Parameter	Type	Required	Default	Description
Return All	boolean	No	false	Whether to return all results or only up to a given limit.
Limit	number	No	5	Max number of results to return. (shown when Return All is false)
Options	collection	No	{}	Extra settings applied to the search.
— Term	string	No	—	A string used to search all the organizations in your team’s address book. This could be an email address, a first name or a last name.
— With Interaction Dates	boolean	No	false	Whether interaction dates will be present on the returned resources.

Organization: Update

Parameter	Type	Required	Default	Description
Organization ID	string	Yes	—	Unique identifier for the organization.
Update Fields	collection	No	{}	The fields to change. Anything you leave out is left as it is.
— Domain	string	No	—	The domain name of the organization.
— Name	string	No	—	The name of the organization.
— Person IDs	string	No	—	Comma-separated IDs of persons to associate with this organization. Find person IDs via Person > Get Many.

Person: Create

Parameter	Type	Required	Default	Description
First Name	string	Yes	—	The first name of the person.
Last Name	string	Yes	—	The last name of the person.
Emails	string	No	—	Comma-separated email addresses of the person.
Additional Fields	collection	No	{}	Optional fields sent with the new person.
— Organization IDs	string	No	—	Comma-separated IDs of organizations to associate with this person. Find organization IDs via Organization > Get Many.

Person: Delete

Parameter	Type	Required	Default	Description
Person ID	string	Yes	—	Unique identifier for the person.

Person: Get

Parameter	Type	Required	Default	Description
Person ID	string	Yes	—	Unique identifier for the person.
Options	collection	No	{}	Extra settings applied to the lookup.
— With Interaction Dates	boolean	No	false	Whether interaction dates will be present on the returned resources.

Person: Get Many

Parameter	Type	Required	Default	Description
Return All	boolean	No	false	Whether to return all results or only up to a given limit.
Limit	number	No	5	Max number of results to return. (shown when Return All is false)
Options	collection	No	{}	Extra settings applied to the search.
— Term	string	No	—	A string used to search all the persons in your team’s address book. This could be an email address, a first name or a last name.
— With Interaction Dates	boolean	No	false	Whether interaction dates will be present on the returned resources.

Person: Update

Parameter	Type	Required	Default	Description
Person ID	string	Yes	—	Unique identifier for the person.
Emails	string	No	—	Comma-separated email addresses of the person. This field is always sent on update.
Update Fields	collection	No	{}	The fields to change. Anything you leave out is left as it is.
— First Name	string	No	—	The first name of the person.
— Last Name	string	No	—	The last name of the person.
— Organization IDs	string	No	—	Comma-separated IDs of organizations to associate with this person. Find organization IDs via Organization > Get Many.

All Operations

Parameter	Type	Required	Default	Description
Max Concurrency	number	No	10	Maximum number of items to process concurrently.

Output Data

Affinity’s response is merged onto the input item’s JSON in every operation — your existing fields survive and the record’s fields are added alongside them, overwriting any key of the same name. Binary data on the input item is forwarded.

Operation	Output items per input item
create, get, update	One — the record merged onto the item.
delete	One — the API’s delete acknowledgement merged onto the item.
getAll	One per record returned, so a single input item fans out across the whole result set.

Two behaviours of getAll are worth planning for:

• A getAll that matches nothing produces no output items at all. The input item does not pass through — that branch of the workflow simply goes quiet. If a downstream node must run regardless, do not depend on this node emitting something.
• Return All changes how much is fetched, not the shape. On, Affinity is paged through until every record is collected. Off, the result is capped at Limit — which accepts values from 1 to 10, so a capped getAll returns at most ten records.

The record fields themselves are whatever Affinity returns; the node does not rename, nest or filter them. Reference them downstream by expression, e.g. {{ $json.id }}.

Example Configuration

Look up one list by ID:

{
  "type": "affinity",
  "parameters": {
    "resource": "list",
    "operation": "get",
    "listId": "{{ $json.listId }}"
  }
}

Create an organization from data on the item:

{
  "type": "affinity",
  "parameters": {
    "resource": "organization",
    "operation": "create",
    "name": "{{ $json.company }}",
    "domain": "{{ $json.domain }}"
  }
}

Search organizations by term, paging through every match:

{
  "type": "affinity",
  "parameters": {
    "resource": "organization",
    "operation": "getAll",
    "returnAll": true,
    "options": {
      "term": "acme",
      "withInteractionDates": true
    }
  }
}

Create a person and attach them to an organization:

{
  "type": "affinity",
  "parameters": {
    "resource": "person",
    "operation": "create",
    "firstName": "{{ $json.firstName }}",
    "lastName": "{{ $json.lastName }}",
    "emails": "{{ $json.email }}",
    "additionalFields": {
      "organizations": "12345"
    }
  }
}

Add an entity to a list:

{
  "type": "affinity",
  "parameters": {
    "resource": "listEntry",
    "operation": "create",
    "listId": "{{ $json.listId }}",
    "entityId": "{{ $json.organizationId }}"
  }
}

Remove a list entry:

{
  "type": "affinity",
  "parameters": {
    "resource": "listEntry",
    "operation": "delete",
    "listId": "{{ $json.listId }}",
    "listEntryId": "{{ $json.listEntryId }}"
  }
}

Error Handling

Mode	Behavior
stop	Halts workflow on first error
continue	Skips failed items, passes successful ones through
errorPort	Routes failed items to Error output port

Tips

Affinity manages organizations, persons, lists and list entries in the Affinity relationship intelligence CRM. It is the right tool when a workflow must create, update, delete or look up organizations and persons, add or delete list entries, or read its lists in Affinity, rather than in another CRM or a plain contact list. It returns the matching records as JSON items, with the getAll operations paging through many organizations, persons, lists or entries.

Important Notes

• Collection type parameters (additionalFields, updateFields, options) use flat object structure
• The emails parameter for persons accepts comma-separated values
• List IDs can be found using the List > Get Many operation
• Entity IDs refer to persons, organizations, or opportunities that can be added to lists
• When updating persons, the emails field is always sent even if not changed