Introduction

Welcome to the Affinity API! This API provides a RESTful interface for performing operations on the different objects that make up Affinity. If you are trying to accomplish an action through this API and are not sure on what endpoints to use, or if you have ideas on more endpoints we could create to make your workflow easier, please do not hesitate to contact us at support@affinity.co.

Getting Started

Authentication

Authentication using HTTP basic auth.

curl "https://api.affinity.co/api_endpoint" -u :$APIKEY

To use the API, you will need to generate an API secret key. This can be done easily through the Settings Panel that is accessible through the left sidebar on the Affinity web app. For more support, visit the How to obtain your API Key article in our Help Center.

Requests are authenticated using HTTP Basic Auth. Provide your API key as the basic auth password. You do not need to provide a username.

Currently, we support one key per user on your team. Once you have generated a key, you will need to pass in the key with every API request for us to process it successfully. Otherwise, an error with a code of 401 will be returned.

Requests & Responses

This is a full-featured RESTful API. We provide reading & writing functionality for each object type in Affinity. All requests use the base URL of https://api.affinity.co/.

Responses to each request are provided as a JSON object. The response is either the data requested, or a valid error message and error code as outlined below.

Here is a list of all the error codes the Affinity API returns in case something does not go as expected:

Rate Limits

API Rate Limits

The Affinity API sets a limit on the number of calls that a user can make per minute, and that all the users on an account can make per month. It also sets a reasonable limit on the number of concurrent requests it will support from an account at one time.

Requests to both Affinity API versions will count toward the one pool of requests allowed for a user or account. Once a per-minute, monthly, or concurrent rate limit is hit, subsequent requests will return an error code of 429. We highly recommend designing your application to handle 429 errors.

Monthly Limits (Account-Level)

Your account plan tier will limit the overall number of requests you can make per month. Current rate limits by plan tier are:

This monthly account-level limit resets at the end of each calendar month.

Per Minute Limits (User-Level)

All API requests will be halted at 900 per user, per minute. We may also lower this limit on a temporary basis to manage API availability.

Concurrent Request Limits (Account-Level)

To protect our systems and manage availability across customers, we set a reasonable limit on concurrent requests at the account level. Customers should not expect to hit this limit unless they are hitting the API with heavy operations from many concurrent threads at once.

Webhook Subscription Limit

There is a limit of three webhook subscriptions per Affinity instance.

Rate Limit Headers

Each external API call will include headers with information about monthly and per-minute limits. This is a convenient way to retrieve your rate limits and usage without needing to hit the /rate-limit endpoint. Every API call will respond with the following headers:

Data Model

Overview

The three top-level objects in Affinity are Persons, Organizations, and Opportunities, and everything in the product is centered around these three resources. We refer to a data model that is a person, organization, or opportunity as an Entity.

The data stored in Affinity can be easily understood as a spreadsheet, with many rows, columns and cells. For each part of a spreadsheet, there are directly equivalent data models in Affinity.

The List view in Affinity represents the spreadsheet itself. A List is a collection of many rows, and the Affinity equivalent of a row is a List Entry. Each column in a spreadsheet is represented by a "Field". There are three types of Fields in Affinity: Global Fields, List-specific Fields and Smart Fields.

The data in each cell is represented by a "Field Value". There are both regular Field Values and Smart Field Values.

Default Fields

By default, Affinity creates some fields for you automatically. Below are the fields created by type:

Common Use Cases

Use the common use cases below to learn how Affinity API endpoints work.

Getting Field Values for All List Entries on a List

1. 1. Query GET /lists to get all lists and filter results by list name to get the appropriate list ID

   GET /lists Response:
   [
     {
       "id": 12058,
       "type": 0,
       "name": "Current Prospects",
       "public": true,
       "owner_id": 477400,
       "list_size": 150
     }
     ...
   ]
   

2. 2. Query GET /lists/12058/list-entries to get all list entries. Store the entity_id associated with each list entry ID

   GET /lists/{list_id}/list-entries Response:
   [
     {
       "id": 37605676,
       "list_id": 113859,
       "creator_id": 63842761,
       "entity_id": 7133202,
       "entity_type": 8,
       "created_at": "2021-09-12T16:29:15.962-07:00",
       "entity": {
         "id": 7133202,
         "name": "Affinity Opportunity"
       }
     }
     ...
   ]
   

3. 3. For each list entry, query GET /field-values with the entity_id from the previous step. Make sure you are passing entity_id through the appropriate parameter (e.g person_id)

   GET /field-values Response:
   [
     {
       "id": 2448594830,
       "field_id": 61223,
       "list_entry_id": 37605676,
       "entity_type": 0,
       "value_type": 3,
       "entity_id": 7133202,
       "value": 5000.0
     }
     ...
   ]
   

4. 4. Locate field values for a given set of fields (optional)

   1. Query GET /fields to get all fields. If the given set of fields are all list-specific, it is helpful to pass along the list_id parameter to prefilter the results
   2. Filter results of GET /fields by field name to get the appropriate field ID
   3. Cross-reference the field_id from Step 3 with the field ID

   GET /fields Response:
   [
     {
       "id": 61223,
       "name": "Amount",
       "list_id": 12058,
       "value_type": 3,
       "allows_multiple": false,
       "track_changes": true,
     }
     ...
   ]
   

Getting Field Value Changes for Status Fields

1. 1. Query GET /lists and filter results to get the appropriate list ID

   GET /lists Response:
   [
     {
       "id": 12058,
       "type": 0,
       "name": "Current Prospects",
       "public": true,
       "owner_id": 477400,
       "list_size": 150
     }
     ...
   ]
   

2. 2. Locate the appropriate status field:

   1. Query GET /fields to get all fields. If the given set of fields are all list-specific, it is helpful to pass along the list_id parameter to prefilter the results
   2. Filter results of GET /fields by field name and cross-reference the list_id with the appropriate list ID from Step 1 to confirm you have the appropriate status field

   GET /fields Response:
   [
     {
       "id": 61223,
       "name": "Amount",
       "list_id": 12058,
       "value_type": 3,
       "allows_multiple": false,
       "track_changes": true,
     },
     ...
   ]
   

3. 3. Query GET /field-values-changes passing in the id from Step 2

   GET /field-values-changes Response:
   [
     {
       "id": 7,
       "entity_attribute_id": 106,
       "changer": {
           "id": 2,
           "type": 1,
           "first_name": "Alice",
           "last_name": "Doe",
           "primary_email": "alice@affinity.co",
           "emails": [
               "alice@affinity.co"
           ]
       },
       "changed_at": "2021-09-17T10:43:12.781-04:00",
       "action_type": 2,
       "list_entry_id": 15709964,
       "person": {
           "id": 2,
           "type": 1,
           "first_name": "John",
           "last_name": "Doe",
           "primary_email": "jdoe@alumni.stanford.edu",
           "emails": [
               "jdoe@alumni.stanford.edu"
           ]
       },
       "company": null,
       "opp": null,
       "value": {
           "id": 30,
           "text": "In Progress",
           "rank": 1,
           "color": 3
       },
       "entity_id": 38706,
       "field_id": 61223
       }
     ...
   ]
   

4. 4. Filter results of GET /field-values-changes (e.g.: If you only want status field changes for a specific organization in your list, search by the list_entry_id).

   GET /field-values-changes Response:
   [
     {
       "id": 7,
       "entity_attribute_id": 106,
       "changer": {
           "id": 2,
           "type": 1,
           "first_name": "Alice",
           "last_name": "Doe",
           "primary_email": "alice@affinity.co",
           "emails": [
               "alice@affinity.co"
           ]
       },
       "changed_at": "2021-09-17T10:43:12.781-04:00",
       "action_type": 2,
       "list_entry_id": 15709964,
       "person": {
           "id": 2,
           "type": 1,
           "first_name": "John",
           "last_name": "Doe",
           "primary_email": "jdoe@alumni.stanford.edu",
           "emails": [
               "jdoe@alumni.stanford.edu"
           ]
       },
       "company": null,
       "opp": null,
       "value": {
           "id": 30,
           "text": "In Progress",
           "rank": 1,
           "color": 3
       },
       "entity_id": 38706,
       "field_id": 61223
       }
     ...
   ]
   

Getting the Strongest Relationship Strength Connection to an Organization on a List

1. 1. Query GET /lists to get all lists and filter results to get the appropriate list ID

   GET /lists Response:
   [
     {
       "id": 12058,
       "type": 0,
       "name": "Current Prospects",
       "public": true,
       "owner_id": 477400,
       "list_size": 150
     }
     ...
   ]
   

2. 2. Query GET /lists/12058/list-entries to get all list entries. Store the entity_id associated with each list entry ID

   GET /lists/{list_id}/list-entries Response:
   [
     {
       "id": 37605676,
       "list_id": 12058,
       "creator_id": 63842761,
       "entity_id": 7133202,
       "entity_type": 8,
       "created_at": "2021-09-12T16:29:15.962-07:00",
       "entity": {
         "id": 7133202,
         "name": "Affinity",
         "domain": "affinity.co",
         "domains": [
           "affinity.co"
         ],
         "crunchbase_uuid": null,
         "global": false
       }
     }
     ...
   ]
   

3. 3. For each list entry, query GET /organizations/{organization_id} to get all list people associated with the organization. Store the person_ids associated with each organization

   GET /organizations/7133202 Response:
   {
     "id": 7133202,
     "name": "Affinity",
     "domain": "affinity.co",
     "domains": ["affinity.co"],
     "crunchbase_uuid": null,
     "global": false,
     "person_ids": [89734, 117270, 138123, 274492, 304848, ...],
     "list_entries": [
       {
         "id": 389,
         "list_id": 26,
         "creator_id": 38603,
         "entity_id": 7133202,
         "entity_type": 0,
         "created_at": "2020-12-11T02:26:56.537-08:00",
       }
       ...
     ]
   }
   

4. 4. For each person ID from Step 3, query GET /relationships-strengths passing in the person ID. Once all person IDs have been looped through, filter for the highest strength

   GET /relationships-strengths Response:
   [
     {
       "internal_id": 26317,
       "external_id": 89734,
       "strength": 0.5
     }
     ...
   ]
   

Useful Resources

• Postman Collection (Right-click and save as JSON then import into Postman)
• Affinity Zapier Integrations
• Affinity Tray Connectors

Partner With Us

If you're a developer interested in building an integration with Affinity's relationship intelligence platform for your customers, please get in touch here.

Spacer

Lists

Lists are the primary data structure that you can interact with in Affinity. Each list manages a collection of either people, organizations or opportunities. We call people, organizations and opportunities "entities".

A list in Affinity is easily represented as a spreadsheet. The rows of the spreadsheet are the list entries, and each list entry corresponds to a single person in a list of people, an organization in a list of organizations or an opportunity in a list of opportunities.

Lists in Affinity can also have any number of custom attributes. These attributes allow you to fully customize your workflow and model the data for your use case. We call these attributes "fields", and each fields represents a column in the spreadsheet representation.

As a simple example: A list called "Important People" might have 25 people in it. Two of the columns in the sheet could be "Title" and "Industry".

This list would have 25 "list entries". Each list entry would be associated with a single person entity. Furthermore, the list would have two "fields" with the names "Title" and "Industry".

The List Resource

Example Response

{
  "id": 450,
  "type": 0,
  "name": "My List of People",
  "public": true,
  "owner_id": 38706,
  "creator_id": 38901,
  "list_size": 67,
  "additional_permissions": [
    {
      "internal_person_id": 38706,
      "role_id": 0
    }
  ]
}

List Types

List-level Roles

See here for details on the permissions held by these roles.

Get All Lists

Example Request

# Returns an array of all lists that you have access to.
curl "https://api.affinity.co/lists" -u :$APIKEY

Example Response

[
  {
    "id": 450,
    "type": 0,
    "name": "My List of People",
    "public": true,
    "owner_id": 38706,
    "list_size": 67
  },
  {
    "id": 383,
    "type": 1,
    "name": "My List of Organizations",
    "public": true,
    "owner_id": 38706,
    "list_size": 50
  },
  ...
]

GET /lists

Returns a collection of all the lists visible to you.

Parameters

None

Returns

An array of all the list resources for lists visible to you. Each list resource in the array includes the id, name, and type (refer to the list resource above for further help).

Get a Specific List

Example Request

# Returns the list with the specified `list_id`
curl "https://api.affinity.co/lists/450" -u :$APIKEY

Example Response

{
  "id": 450,
  "type": 0,
  "name": "My List of People",
  "public": true,
  "owner_id": 38706,
  "list_size": 67
  "fields": [
    {
      "id": 1625,
      "name": "Status",
      "value_type": 7,
      "allows_multiple": false,
      "dropdown_options": [
        {
          "id": 886,
          "text": "Interested",
          "rank": 1,
          "color": 0
        }
      ]
    },
    {
      "id": 1626,
      "name": "Owners",
      "value_type": 0,
      "allows_multiple": true,
      "dropdown_options": [],
    },
    ...
  ]
}

GET /lists/{list_id}

Gets the details for a specific list given the existing list id.

Path Parameters

Returns

The details of the list resource corresponding to the list ID specified in the path parameter. These details include an array of the fields that are specific to this list. An appropriate error is returned if an invalid list is supplied.

Create a New List

Example Request

curl -X POST “https://api.affinity.co/lists” \
   -u :$APIKEY \
   -H "Content-Type: application/json" \
   -d '{ "name": "My List of Organizations", "type": 1, "is_public": true, "owner_id": 38706, "additional_permissions": [ {"internal_person_id": 38701, "role_id": 0}, {"internal_person_id": 38703, "role_id": 1}, {"internal_person_id": 38900, "role_id": 0} ]}'

Example Response

{
  "id": 383,
  "type": 1,
  "name": "My List of Organizations",
  "public": true,
  "owner_id": 38706,
  "creator_id": 38701,
  "list_size": 0,
  "additional_permissions": [
    {
      "internal_person_id": 38701,
      "role_id": 0
    },
    {
      "internal_person_id": 38703,
      "role_id": 1
    },
    {
      "internal_person_id": 38900,
      "role_id": 0
    }
  ]
}

POST /lists

Creates a new list with the supplied parameters.

Payload Parameters

Returns

The list resource that was just created through this request.

List Entries

The List Entry Resource

Example Response

{
  "id": 16367,
  "list_id": 450,
  "creator_id": 38706,
  "entity_id": 287125,
  "entity": {
    "type": 1,
    "first_name": "John",
    "last_name": "Doe",
    "primary_email": "jdoe@jdoe.com",
    "emails": ["jdoe@jdoe.com", "jdoe2@jdoe2.com"]
  },
  "created_at": "2017-01-16T16:34:03.539-08:00"
}

Each list comprises a number of entries. Each list entry has a creator, a list that it belongs to, and the underlying entity it represents depending on the type of the list (people, organizations or opportunities).

Operations like adding and removing entities from a list can be accomplished using the list entry abstraction.

Get All List Entries

Example Request

curl "https://api.affinity.co/lists/450/list-entries" -u :$APIKEY

Example Response

[
  {
    "id": 64608,
    "list_id": 450,
    "creator_id": 287843,
    "entity_id": 62034,
    "created_at": "2017-05-04T10:44:31.525-08:00",
    "entity": {
      "type": 0,
      "first_name": "Affinity",
      "last_name": "Team",
      "primary_email": "team@affinity.co",
      "emails": [
        "team@affinity.co"
      ],
    },
  },
  {
    "id": 53510,
    "list_id": 450,
    "creator_id": 38596,
    "entity_id": 241576,
    "created_at": "2017-02-22T15:22:21.125-08:00",
    "entity": {
      "type": 0,
      "first_name": "John",
      "last_name": "Doe",
      "primary_email": "jdoe@stanford.edu",
      "emails": [
        "jdoe@stanford.edu"
      ],
    },
  },
  ...
]

Example Response with Pagination

{
  "list_entries": [
    {
      "id": 64608,
      "list_id": 450,
      "creator_id": 287843,
      "entity_id": 62034,
      "created_at": "2017-05-04T10:44:31.526-08:00",
      "entity": {
        "type": 0,
        "first_name": "Affinity",
        "last_name": "Team",
        "primary_email": "team@affinity.co",
        "emails": [
          "team@affinity.co"
        ],
      },
    },
    {
      "id": 53510,
      "list_id": 450,
      "creator_id": 38596,
      "entity_id": 241576,
      "created_at": "2017-02-22T15:22:21.125-08:00",
      "entity": {
        "type": 0,
        "first_name": "John",
        "last_name": "Doe",
        "primary_email": "jdoe@stanford.edu",
        "emails": [
          "jdoe@stanford.edu"
        ],
      },
    },
    ...
  ],
  "next_page_token": "eyJwYXJhbXMiOnsidGVybSI6IiJ9LCJwYWdlX3NpemUiOjUsIm9mZnNldCI6MTB9"
}

GET /lists/{list_id}/list-entries

If no page size is specified, fetches all the list entries in the list with the supplied list id. If a page size is specified, fetches up to that number of list entries in the list with the supplied list id.

Path Parameters

Query Parameters

Returns

If the page_size is not passed in as a parameter, an array of all the list entry resources corresponding to the provided list will be returned. If the page_size is passed in as a parameter, an object with two fields: list_entries and next_page_token are returned. list_entries maps to an array of up to page_size list entries. next_page_token includes a token to be sent along with the next request as the page_token parameter to fetch the next page of results. Each list entry in the both cases includes all the attributes as specified in the List Entry Resource section above.

Get a Specific List Entry

GET /lists/{list_id}/list-entries/{list_entry_id}

Fetches a list entry with a specified id.

Example Request

curl "https://api.affinity.co/lists/450/list-entries/16367" -u :$APIKEY

Example Response

{
  "id": 16367,
  "list_id": 450,
  "creator_id": 38596,
  "entity_id": 241576,
  "created_at": "2017-02-22T15:22:21.125-08:00",
  "entity": {
    "type": 0,
    "first_name": "John",
    "last_name": "Doe",
    "primary_email": "jdoe@stanford.edu",
    "emails": ["jdoe@stanford.edu"]
  }
}

Path Parameters

Returns

The list entry object corresponding to the list_entry_id.

Create a New List Entry

Example Request

curl -X POST “https://api.affinity.co/lists/450/list-entries” \
   -u :$APIKEY \
   -H "Content-Type: application/json" \
   -d '{"entity_id": 38706}'

Example Response

{
  "id": 53510,
  "list_id": 450,
  "creator_id": 38596,
  "entity_id": 38706,
  "created_at": "2017-02-22T15:22:21.125-08:00",
  "entity": {
    "type": 0,
    "first_name": "John",
    "last_name": "Doe",
    "primary_email": "jdoe@stanford.edu",
    "emails": ["jdoe@stanford.edu"]
  }
}

POST /lists/{list_id}/list-entries

Creates a new list entry in the list with the supplied list id.

Path Parameters

Payload Parameters

Returns

The list entry resource that was just created through this request.

Delete a Specific List Entry

Example Request

curl "https://api.affinity.co/lists/450/list-entries/56517" \
   -u :$APIKEY \
   -X "DELETE"

Example Response

{ "success": true }

DELETE /lists/{list_id}/list-entries/{list_entry_id}

Deletes a list entry with a specified list_entry_id.

Path Parameters

Returns

The JSON object {"success": true}.

Fields

As discussed in the previous section, fields as a data model represent the "columns" in a spreadsheet. A field can be specific to a given list, or it can be global. List-specific fields appear as a column whenever that list is being viewed while global fields are displayed on all lists.

Let us consider two examples:

1. Assume you have a list called "Top Referrers", and a new list-specific field (column) called "Number of Referrals" is added to this list. In this case, the "Number of Referrals" column will only be visible on the "Top Referrers" list.

2. Now assume you have three lists of people, "Top Referrers", "Friends in Media", "BD Leads", and a person X exists on all three lists. If you want to track where all the people in these 3 lists live, you might have a field called "Location". It makes sense to make this field global - in which case it will be shared across all three lists. Hence, if person X is a top referrer and lives in San Francisco, CA, that information will automatically appear on the "Friends in Media" list as well.

By default, Affinity provides all teams with a few default global fields: For people, the global fields include Location, Job Titles, and Industries. For organizations, the global fields include Stage, Industry, Location, and more.

The Field Resource

Example Response

{
  "id": 1234,
  "name": "Deal Status",
  "list_id": 11,
  "enrichment_source": "none",
  "value_type": 7,
  "allows_multiple": false,
  "track_changes": true,
  "dropdown_options": [
    {
      "id": 2863451,
      "text": "New",
      "rank": 0,
      "color": 3
    },
    {
      "id": 2863452,
      "text": "In Progress",
      "rank": 1,
      "color": 3
    },
    {
      "id": 2863453,
      "text": "Won",
      "rank": 2,
      "color": 2
    }
  ]
}

Each field object has a unique id. It also has a name, which determines the name of the field, and allows_multiple, which determines whether multiple values can be added to a single cell for that field.

Affinity is extremely flexible and customizable, and a lot of that power comes from our ability to support many different value types for fields. Numbers, dates, and locations are all examples of value types, and you can search, sort, or filter all of them.

Field Value Types

All the Types listed below can be referred through looking at the Affinity web app as well.

Get Fields

Example Request

curl "https://api.affinity.co/fields?with_modified_names=true" -u :$APIKEY

Example Response

[
  {
    "id": 1234,
    "name": "[Deals] Amount",
    "list_id": 11,
    "enrichment_source": "none",
    "value_type": 3,
    "allows_multiple": false,
    "track_changes": true,
    "dropdown_options": []
  },
  {
    "id": 5678,
    "name": "[Events] Amount",
    "list_id": 16,
    "enrichment_source": "none",
    "value_type": 3,
    "allows_multiple": false,
    "track_changes": true,
    "dropdown_options": []
  },
  {
    "id": 4321,
    "name": "[Companies] Description",
    "list_id": 18,
    "enrichment_source": "dealroom",
    "value_type": 6,
    "allows_multiple": false,
    "track_changes": false,
    "dropdown_options": []
  },
  ...
]

GET /fields

Returns all fields based on the parameters provided.

Pass the list_id to only fetch fields that are specific to that list. Otherwise, all global and list-specific fields will be returned.

Pass the value_type to fetch fields of specific value types. Otherwise, all fields of any type will be returned.

Pass the entity_type to fetch fields of specific entity types. Otherwise, any fields of any entity type will be returned.

Pass the with_modified_names flag to return the fields such that the names have the list name prepended to them in the format [List Name] Field Name (i.e. [Deals] Status).

Pass the exclude_dropdown_options flag to exclude dropdown options from the response. This may be useful when the payload is too large due to too many dropdown options.

Query Parameters

Returns

An array of all the fields requested.

Create Field

Example Request

curl -X POST "https://api.affinity.co/fields" \
  -u :$APIKEY \
  -H "Content-Type: application/json" \
  -d '{"name": "[Deals] Amount", "list_id": 11, "entity_type": 1, "value_type": 3, "allows_multiple": false, "is_list_specific": true}'

Example Response

{
  "id": 59,
  "name": "[Deals] Amount",
  "list_id": 11,
  "enrichment_source": "none",
  "value_type": 3,
  "allows_multiple": false,
  "track_changes": false,
  "dropdown_options": []
}

POST /fields

Creates a new field with the supplied parameters.

Payload Parameters

Field Entity Types

Returns

The field resource that was just created through this request.

Delete a Field

Example Request

curl "https://api.affinity.co/fields/1234" \
  -u :$APIKEY \
  -X "DELETE"

Example Response

{ "success": true }

DELETE /fields/{id}

Deletes an field with the specified id.

Path Parameters

Returns

{success: true}.

Field Values

Field values are displayed in Affinity as the data in the cells of an Affinity spreadsheet.

As an example for how a field value is created:

1. Assume there exists a list of people called "Business Development Leads".
2. A custom field called "Deal Size" is created on this list. Fields are visually displayed as columns.
3. A person X is added to this list. This action creates a list entry for this person.
4. A value, 50,000, is entered in the cell corresponding to person X in the Deal Size column.
5. 50,000 is now a field value tied to the list entry corresponding to person X, and the "Deal Size" field.

The Field Value Resource

Example Response (Global Location Field Value)

{
  "id": 250616,
  "field_id": 337,
  "list_entry_id": null,
  "entity_id": 38706,
  "created_at": "2022-10-04T08:54:24.694-04:00",
  "updated_at": null,
  "value": {
    "city": "San Francisco",
    "state": "California",
    "country": "United States",
    "continent": null,
    "street_address": null
  }
}

Example Response (List Specific Dropdown Field Value)

{
  "id": 177634,
  "field_id": 751,
  "list_entry_id": 605,
  "entity_id": 38706,
  "created_at": "2021-10-04T08:54:24.694-04:00",
  "updated_at": "2022-03-04T08:54:24.694-04:00",
  "value": {
    "id": 71,
    "text": "Low",
    "rank": 1,
    "color": 4
  }
}

Each field value object has a unique id.

A field value also has field_id, entity_id, and list_entry_id attributes that give it the appropriate associations, as noted in the example above.

Use the created_at and updated_at timestamps on field values to determine when the value(s) for a given field have last been added or changed. Please note that what might amount to an “update” in-product (e.g. for dropdown fields) might result in a newly created field value rather than an updated old one in the API.

A field value can take on many different kinds of values, depending on the field value type (see Fields section).

Field Value Value Types

The Field Type specified below corresponds to the value_type of a field.

Get Field Values

Example Request

curl "https://api.affinity.co/field-values?person_id=38706" -u :$APIKEY

Example Response

[
  {
    "id": 250616,
    "field_id": 337,
    "list_entry_id": null,
    "entity_id": 38706,
    "created_at": "2021-10-04T08:54:24.694-04:00",
    "updated_at": "2022-03-04T08:54:24.694-04:00",
    "value": {
      "city": "San Francisco",
      "state": "California",
      "country": "United States",
      "continent": null,
      "street_address": null
    }
  },
  {
    "id": 2634897436,
    "field_id": 768101,
    "list_entry_id": null,
    "entity_type": 0,
    "value_type": 2,
    "entity_id": 65680071,
    "created_at": "2022-10-04T08:54:24.694-04:00",
    "updated_at": null,
    "value": "Software Engineer"
  },
  {
    "id": 32760,
    "field_id": 198,
    "list_entry_id": null,
    "entity_id": 38706,
    "created_at": "2022-09-04T08:54:24.694-04:00",
    "updated_at": null,
    "value": 38659
  },
  ...
]

GET /field-values

Returns all field values attached to a person, organization, opportunity, or list_entry.

Query Parameters

Returns

An array of all the field values associated with the supplied person, organization, opportunity, or list_entry.

Create a New Field Value

Example Request

curl -X POST "https://api.affinity.co/field-values" \
  -u :$APIKEY \
  -H "Content-Type: application/json" \
  -d '{"field_id": 1284, "value": "Architecture", "entity_id": 38706}'

Example Response

{
  "id": 20406836,
  "field_id": 1284,
  "list_entry_id": null,
  "entity_id": 38706,
  "created_at": "2022-10-04T10:37:19.418-04:00",
  "updated_at": null,
  "value": "Architecture"
}

POST /field-values

Creates a new field value with the supplied parameters.

Payload Parameters

Returns

The field value resource that was just created through this request.

Update a Field Value

Example Request

curl -X PUT "https://api.affinity.co/field-values/20406836" \
  -u :$APIKEY \
  -H "Content-Type: application/json" \
  -d '{"value": "Healthcare"}'

Example Response

{
  "id": 20406836,
  "field_id": 1284,
  "list_entry_id": null,
  "entity_id": 38706,
  "created_at": "2022-10-04T10:37:19.418-04:00",
  "updated_at": "2023-02-06T11:53:08.914-05:00",
  "value": "Healthcare"
}

PUT /field-values/{field_value_id}

Updates the existing field value with field_value_id with the supplied parameters.

Path Parameters

Payload Parameters

Returns

The field value object that was just updated through this request.

Delete a Field Value

Example Request

curl "https://api.affinity.co/field-values/20406836" \
  -u :$APIKEY \
  -X "DELETE"

Example Response

{ "success": true }

DELETE /field-values/{field_value_id}

Deletes an field value with the specified field_value_id.

Path Parameters

Returns

{success: true}.

Field Value Changes

Field value changes allow you to see historical changes to the values of fields in Affinity. This is especially useful for tracking progress through statuses (e.g. Lead --> Closed Won).

Supported field types

Not all fields can track historical changes.

Fields that are automatically created and "enriched" by Affinity do not support change tracking.

Among fields that are not enriched, only the ones with the following data types support change tracking:

Multi-valued Fields

Single-valued fields

The Field Value Change Resource

Example Response

{
  "id": 50822718,
  "field_id": 236333,
  "entity_id": 261131046,
  "list_entry_id": 15709964,
  "action_type": 0,
  "changer": {
    "id": 38706,
    "type": 0,
    "first_name": "Jane",
    "last_name": "Doe",
    "primary_email": "jane@gmail.com",
    "emails": ["jane@gmail.com"]
  },
  "changed_at": "2020-04-11T15:46:50.963-07:00",
  "value": {
    "id": 1607859,
    "text": "New",
    "rank": 1,
    "color": 0
  }
}

Each field value change object has a unique id.

A field value change also has field_id, entity_id, list_entry_id attributes that give it the appropriate associations, as noted in the example above.

Field Value Change action types

The action type specified below corresponds to the action_type of a field value change. This attribute filters the field value changes that are returned. For example, when an action_type of 0 is specified, all the field value change objects that are returned will represent when a field value has been created.

Get Field Values Changes

Example Request

curl "https://api.affinity.co/field-value-changes?field_id=236333" -u :$APIKEY

Example Response

[
  {
    "id": 50822718,
    "field_id": 236333,
    "entity_id": 261131046,
    "list_entry_id": 15709964,
    "action_type": 0,
    "changer": {
      "id": 38706,
      "type": 0,
      "first_name": "Jane",
      "last_name": "Doe",
      "primary_email": "jane@gmail.com",
      "emails": ["jane@gmail.com"]
    },
    "changed_at": "2020-04-11T15:46:50.963-07:00",
    "value": {
      "id": 1607859,
      "text": "New",
      "rank": 1,
      "color": 0
    }
  }
]

GET /field-value-changes

Returns all field values changes attached to a specific field. Field value changes can be filtered by action_type, person, organization, opportunity or list_entry by passing in the appropriate parameter.

Query Parameters

Returns

An array of all the field values changes associated with the supplied field and person, organization, opportunity or list_entry if specified.

Persons

The persons API allows you to manage all the contacts of your organization. These people include anyone your team has ever been in email communications or meetings with, and all the people that your team has added to Affinity either manually or through the API. Affinity's data model also guarantees that only one person in your team's shared contact list has a given email address.

The Person Resource

Example Response

{
  "id": 38706,
  "type": 0,
  "first_name": "John",
  "last_name": "Doe",
  "primary_email": "john@affinity.co",
  "emails": [
    "john@affinity.co",
    "jdoe@alumni.stanford.edu",
    "johnjdoe@gmail.com",
  ],
  "organization_ids": [
    1687449,
    ...
  ],
  "opportunity_ids": [
    4,
    11,
    ...
  ],
  "current_organization_ids": [1687449],
  "list_entries": [
    {
      "id": 388,
      "list_id": 26,
      "creator_id": 38603,
      "entity_id": 38706,
      "created_at": "2015-12-11T02:26:56.537-08:00",
    },
    ...
  ],
  "interaction_dates": {
    "first_email_date": "2011-11-23T08:12:45.328-08:00",
    "last_email_date": "2012-03-04T05:06:07.890-08:00",
    "last_event_date": "2011-12-11T02:26:56.537-08:00",
    "last_chat_message_date": "2011-11-01T02:26:56.537-08:00",
    "last_interaction_date": "2012-03-04T05:06:07.890-08:00",
    "next_event_date": "2019-03-04T05:06:07.890-08:00",
    "first_event_date": "2012-01-01T08:18:00.329-08:00",
  },
  "interactions": {
    "first_email": {
      "date": "2011-11-23T08:12:45.328-08:00",
      "person_ids": [
        123
      ]
    },
    "last_email": {
      "date": "2012-03-04T05:06:07.890-08:00",
      "person_ids": [
        123
      ]
    },
    "last_event": {
      "date": "2011-12-11T02:26:56.537-08:00",
      "person_ids": [
        123
      ]
    },
    "last_chat_message": {
      "date": "2011-11-01T02:26:56.537-08:00",
      "person_ids": [
        123
      ]
    },
    "last_interaction": {
      "date": "2012-03-04T05:06:07.890-08:00",
      "person_ids": [
        123,
        111
      ]
    },
    "next_event": {
      "date": "2019-03-04T05:06:07.890-08:00",
      "person_ids": [
        123,
        124,
        125
      ]
    },
    "first_event": {
      "date": "2012-01-01T08:18:00.329-08:00",
      "person_ids": [
        123
      ]
    }
  }
}

Each person resource is assigned a unique id and stores the name, type, and email addresses of the person. A person resource also has access to a smart attribute called primary_email. The value of primary_email is automatically computed by Affinity's proprietary algorithms and refers to the email that is most likely to be the current active email address of a person.

The person resource organization_ids is a collection of unique identifiers to the person's associated organizations. Note that a person can be associated with multiple organizations. For example, say your team has talked with organizations A and B. Person X used to work at A and was your point of contact, but then changed jobs and started emailing you from a new email address (corresponding to organization B). In this case, Affinity will automatically associate person X with both organization A and organization B.

The person resource type indicates whether a person is internal or external to your team. Every internal person is a user of Affinity on your team, and all other people are externals.

Dates of the most recent and upcoming interactions with a person are available in the interaction_dates field. This data is only included when passing with_interaction_dates=true as a query parameter to the /persons or the /persons/{person_id} endpoints.

Person types

Search for Persons

GET /persons

Searches your teams data and fetches all the persons that meet the search criteria. The search term can be part of an email address, a first name or a last name.

This result is paginated. An initial request returns an object with two fields: persons and next_page_token. persons contains an array of person resources. The value of next_page_token should be sent as the query parameter page_token in another request to retrieve the next page of results. While paginating through results, each request must have identical query parameters other than the changing page_token. Otherwise, an Invalid page_token variable error will be returned.

The absence of a next_page_token indicates that all the records have been fetched, though its presence does not necessarily indicate that there are more resources to be fetched. The next page may be empty (but then next_page_token would be null to confirm that there are no more resources).

Pass with_interaction_dates=true as a query parameter to include dates of the most recent and upcoming interactions with persons. When this parameter is included, persons with no interactions will not be returned in the response. Pass with_interaction_persons=true as a query parameter if with_interaction_dates=true to also get the internal persons associated with the interaction.

You can filter by interaction dates by providing additional query parameters like min_last_email_date or max_next_event_date. The value of these query parameters should be ISO 8601 formatted date strings.

Example Request

curl "https://api.affinity.co/persons?term=doe" -u :$APIKEY

Example Response

{
  "persons": [
    {
      "id": 38706,
      "type": 0,
      "first_name": "John",
      "last_name": "Doe",
      "primary_email": "john@affinity.co",
      "emails": [
        "john@affinity.co",
        "jdoe@alumni.stanford.edu",
        "johnjdoe@gmail.com",
      ]
    },
    {
      "id": 624289,
      "type": 1,
      "first_name": "Jane",
      "last_name": "Doe",
      "primary_email": "jane@gmail.com",
      "emails": [
        "jane@gmail.com"
      ]
    },
    ...
  ],
  "next_page_token": "eyJwYXJhbXMiOnsidGVybSI6IiJ9LCJwYWdlX3NpemUiOjUsIm9mZnNldCI6MTB9"
}

Example Pagination

# To get the second page of results, issue the following query:
curl "https://api.affinity.co/persons?term=doe&page_token=eyJwYXJhbXMiOnsidGVybSI6IiJ9LCJwYWdlX3NpemUiOjUsIm9mZnNldCI6MTB9" -u :$APIKEY

Example with Interaction Date

# To get the results between min_last_email_interaction_date and max_last_email_interaction_date, issue the following query:
curl "https://api.affinity.co/persons" \
  -u :$APIKEY \
  -H "Content-Type: application/json" \
  -d '{"min_last_email_date": "2021-01-01T00:00:00", "with_interaction_dates": true, "max_last_email_date": "2021-01-12T23:59:59"}'

Query Parameters

Returns

An object with two fields: persons and next_page_token. persons maps to an array of all the person resources that match the search criteria. Does not include the associated organization_ids or list_entries. next_page_token includes a token to be sent along with the next request as the page_token parameter to fetch the next page of results. When with_interaction_dates is passed in the returned resources will have interaction_dates fields.

Get a Specific Person

Example Request

curl "https://api.affinity.co/persons/38706?with_opportunities=true&with_current_organizations=true" \
  -u :$APIKEY \

Example Response

{
  "id": 38706,
  "type": 0,
  "first_name": "John",
  "last_name": "Doe",
  "primary_email": "john@affinity.co",
  "emails": [
    "john@affinity.co",
    "jdoe@alumni.stanford.edu",
    "johndoe@gmail.com",
  ],
  "organization_ids": [1687449],
  "opportunity_ids": [
    4,
    11,
    ...
  ],
  "current_organization_ids": [1687449],
  "list_entries": [
    {
      "id": 388,
      "list_id": 26,
      "creator_id": 38603,
      "entity_id": 38706,
      "created_at": "2015-12-11T02:26:56.537-08:00",
    },
    ...
  ],
}

GET /persons/{person_id}

Fetches a person with a specified person_id.

Path Parameters

Returns

The person resource corresponding to the person_id.

Create a New Person

Example Request

curl -X POST "https://api.affinity.co/persons" \
   -u :$APIKEY \
   -H "Content-Type: application/json" \
   -d '{"first_name": "Alice", "last_name": "Doe", "emails": ["alice@affinity.co"], "organization_ids": [1687449]}'

Example Response

{
  "id": 860197,
  "type": 0,
  "first_name": "Alice",
  "last_name": "Doe",
  "primary_email": "alice@affinity.co",
  "emails": ["alice@affinity.co"],
  "organization_ids": [1687449]
}

POST /persons

Creates a new person with the supplied parameters.

Payload Parameters

Returns

The person resource was newly created from this successful request.

Update a person

Example Request

curl -X PUT "https://api.affinity.co/persons/860197" \
   -u :$APIKEY \
   -H "Content-Type: application/json" \
   -d '{"first_name": "Allison", "emails": ["allison@affinity.co", "allison@gmail.com"]}'

Example Response

{
  "id": 860197,
  "type": 0,
  "first_name": "Allison",
  "last_name": "Doe",
  "primary_email": "alice@affinity.co",
  "emails": ["alice@affinity.co", "allison@example.com", "allison@gmail.com"],
  "organization_ids": [1687449]
}

PUT /persons/{person_id}

Updates an existing person with person_id with the supplied parameters. Only attributes that need to be changed must be passed in.

Path Parameters

Payload Parameters

Returns

The person object that was just updated through this request.

Delete a Person

Example Request

curl "https://api.affinity.co/persons/860197" \
  -u :$APIKEY \
  -X "DELETE"

Example Response

{ "success": true }

DELETE /persons/{person_id}

Deletes a person with a specified person_id.

Path Parameters

Returns

{success: true}.

Get Global Person Fields

GET /persons/fields

Fetches an array of all the global fields that exist on people. If you aren't sure about what fields are, please read the Fields section first.

Example Request

curl "https://api.affinity.co/persons/fields" -u :$APIKEY

Example Response

[
  {
    "id": 125,
    "name": "Use Case",
    "value_type": 2,
    "allows_multiple": true,
    "dropdown_options": []
  },
  {
    "id": 198,
    "name": "Referrers",
    "value_type": 0,
    "allows_multiple": true,
    "dropdown_options": []
  },
  {
    "id": 1615,
    "name": "Address",
    "value_type": 5,
    "allows_multiple": false,
    "dropdown_options": []
  },
  ...
]

Parameters

None.

Returns

An array of the global fields that exist on people for your team.

Organizations

An organization in Affinity represents an external company that your team is in touch with- this could be an organization you're trying to invest in, sell to, or establish a relationship with.

An organization has many people associated with it - these are your team's points of contacts at that organization. Just like people, organizations can be added to multiple lists and can be assigned field values.

To make the data quality as good as possible, we have our own proprietary database of organizations that we have developed through third-party partnerships and web scraping. We use this database to minimize data entry for you as you use Affinity's CRM products.

The Organization Resource

Example Response

{
  "id": 64779194,
  "name": "Affinity",
  "domain": "affinity.co",
  "domains": ["affinity.co"],
  "global": false,
  "person_ids": [
    89734,
    117270,
    138123,
    274492,
    304848,
    ...],
  "opportunity_ids": [
    4,
    11,
    ...
  ],
  "list_entries": [
    {
      "id": 389,
      "list_id": 26,
      "creator_id": 38603,
      "entity_id": 64779194,
      "created_at": "2015-12-11T02:26:56.537-08:00",
    },
    ...
  ],
  "interaction_dates": {
    "first_email_date": "2011-11-23T08:12:45.328-08:00",
    "last_email_date": "2012-03-04T05:06:07.890-08:00",
    "last_event_date": "2011-12-11T02:26:56.537-08:00",
    "last_chat_message_date": "2011-11-01T02:26:56.537-08:00",
    "last_interaction_date": "2012-03-04T05:06:07.890-08:00",
    "next_event_date": "2019-03-04T05:06:07.890-08:00",
    "first_event_date": "2012-01-01T08:18:00.329-08:00",
  },
  "interactions": {
    "first_email": {
      "date": "2011-11-23T08:12:45.328-08:00",
      "person_ids": [
        123
      ]
    },
    "last_email": {
      "date": "2012-03-04T05:06:07.890-08:00",
      "person_ids": [
        123
      ]
    },
    "last_event": {
      "date": "2011-12-11T02:26:56.537-08:00",
      "person_ids": [
        123
      ]
    },
    "last_chat_message": {
      "date": "2011-11-01T02:26:56.537-08:00",
      "person_ids": [
        123
      ]
    },
    "last_interaction": {
      "date": "2012-03-04T05:06:07.890-08:00",
      "person_ids": [
        123,
        111
      ]
    },
    "next_event": {
      "date": "2019-03-04T05:06:07.890-08:00",
      "person_ids": [
        123,
        124,
        125
      ]
    },
    "first_event": {
      "date": "2012-01-01T08:18:00.329-08:00",
      "person_ids": [
        123
      ]
    }
  }
}

Each organization object has a unique id. It also has a name, domain (the website of the organization), and persons associated with it. The domain is an important attribute from an automation perspective, as it helps Affinity automatically link all the appropriate person objects to the organization.

Each organization also has a flag determining whether it's global or not. As mentioned above, Affinity maintains its own database of global organizations that each customer has access to. Note that you cannot change the name or the domain of a global organization. You also cannot delete a global organization.

Of course, if an organization is manually created by your team, all fields can be modified and the organization can be deleted.

Dates of the most recent and upcoming interactions with an organization are available in the interaction_dates field. This data is only included when passing with_interaction_dates=true as a query parameter to the GET /organizations or the GET /organizations/{organization_id} endpoints.

Search for Organizations

GET /organizations

Searches your team's data and fetches all the organizations that meet the search criteria. The search term can be a part of an organization's name or domain.

This result is paginated. An initial request returns an object with two fields: organizations and next_page_token. organizations contains an array of organization resources. The value of next_page_token should be sent as the query parameter page_token in another request to retrieve the next page of results. While paginating through results, each request must have identical query parameters other than the changing page_token. Otherwise, an Invalid page_token variable error will be returned.

The absence of a next_page_token indicates that all the records have been fetched, though its presence does not necessarily indicate that there are more resources to be fetched. The next page may be empty (but then next_page_token would be null to confirm that there are no more resources).

Pass with_interaction_dates=true as a query parameter to include dates of the most recent and upcoming interactions with organizations. When this parameter is included, organizations with no interactions will not be returned in the response. Pass with_interaction_persons=true as a query parameter if with_interaction_dates=true to also get the internal persons associated with the interaction.

You can filter by interaction dates by providing additional query parameters like min_last_email_date or max_next_event_date. The value of these query parameters should be ISO 8601 formatted date strings. The interaction dates are stored with timestamps, so the {min,max}_<interaction>_date parameter can include or exclude timestamps to explicitly filter the dataset. If a timestamp is not provided, the system will use the default value of 00:00:00.

Example Request

curl "https://api.affinity.co/organizations?term=affinity" -u :$APIKEY

Example Response

{
  "organizations": [
    {
      "id": 64779194,
      "name": "Affinity",
      "domain": "affinity.co",
      "domains": ["affinity.co"],
      "global": false
    },
    {
      "id": 1513682,
      "name": "Brand Affinity Technologies",
      "domain": "brandaffinity.net",
      "domains": ["brandaffinity.net"],
      "global": true
    },
    ...
  ],
  "next_page_token": "eyJwYXJhbXMiOnsidGVybSI6IiJ9LCJwYWdlX3NpemUiOjUsIm9mZnNldCI6MTB9",
}

Example Pagination

# To get the second page of results, issue the following query:
curl "https://api.affinity.co/organizations" \
  -u :$APIKEY \
  -d page_token=eyJwYXJhbXMiOnsidGVybSI6IiJ9LCJwYWdlX3NpemUiOjUsIm9mZnNldCI6MTB9

Example with Interaction Date

# To get the results between min_last_email_interaction_date and max_last_email_interaction_date, issue the following query:
curl "https://api.affinity.co/organizations" \
  -u :$APIKEY \
  -H "Content-Type: application/json" \
  -d '{"min_last_email_date": "2021-01-01T00:00:00", "with_interaction_dates": true, "max_last_email_date": "2021-01-12T23:59:59"}'

Query Parameters

Returns

An object with two fields: organizations and next_page_token. organizations maps to an array of all the organization resources that match the search criteria. next_page_token includes a token to be sent along with the next request as the page_token parameter to fetch the next page of results. When with_interaction_dates is passed in the returned resources will have interaction_dates fields.

Get a Specific Organization

Example Request

curl "https://api.affinity.co/organizations/64779194" -u :$APIKEY

Example Response

{
  "id": 64779194,
  "name": "Affinity",
  "domain": "affinity.co",
  "domains": ["affinity.co"],
  "global": false,
  "person_ids": [
    89734,
    117270,
    138123,
    274492,
    304848,
    ...
  ],
  "opportunity_ids": [
    4,
    11,
    ...
  ],
  "list_entries": [
    {
      "id": 389,
      "list_id": 26,
      "creator_id": 38603,
      "entity_id": 64779194,
      "created_at": "2015-12-11T02:26:56.537-08:00",
    },
    ...
  ],
}

GET /organizations/{organization_id}

Fetches an organization with a specified organization_id.

Path Parameters

Returns

The organization object corresponding to the organization_id.

Create a New Organization

Example Request

curl -X POST "https://api.affinity.co/organizations" \
   -u :$APIKEY \
   -H "Content-Type: application/json" \
   -d '{"name": "Acme Corporation", "domain": "acme.co", "person_ids": [38706]}'

Example Response

{
  "id": 120611418,
  "name": "Acme Corporation",
  "domain": "acme.co",
  "domains": ["acme.co"],
  "global": false,
  "person_ids": [38706]
}

POST /organizations

Creates a new organization with the supplied parameters.

Payload Parameters

Returns

The organization resource that was just created by a successful request.

Update an Organization

Example Request

curl -X PUT "https://api.affinity.co/organizations/120611418" \
   -u :$APIKEY \
   -H "Content-Type: application/json" \
   -d '{"name": "Acme Corp.", "person_ids": [38706, 89734]}'

Example Response

{
  "id": 120611418,
  "name": "Acme Corp.",
  "domain": "acme.co",
  "domains": ["acme.co"],
  "global": false,
  "person_ids": [38706, 89734]
}

PUT /organizations/{organization_id}

Updates an existing organization with organization_id with the supplied parameters.

Path Parameters

Payload Parameters

Returns

The organization resource that was just updated through a successful request.

Delete an Organization

Example Request

curl "https://api.affinity.co/organizations/120611418" \
  -u :$APIKEY \
  -X "DELETE"

Example Response

{ "success": true }

DELETE /organizations/{organization_id}

Deletes an organization with a specified organization_id.

Path Parameters

Returns

{success: true}.

Get Global Organizations Fields

Example Request

curl "https://api.affinity.co/organizations/fields" -u :$APIKEY

Example Response

[
  {
    "id": 662,
    "name": "Potential Users",
    "value_type": 3,
    "allows_multiple": false,
    "dropdown_options": []
  },
  {
    "id": 700,
    "name": "Leads",
    "value_type": 0,
    "allows_multiple": true,
    "dropdown_options": []
  },
  {
    "id": 2988,
    "name": "Last Funding Date",
    "value_type": 4,
    "allows_multiple": false,
    "dropdown_options": []
  },
  ...
]

GET /organizations/fields

Fetches an array of all the global fields that exist on organizations. If you aren't sure about what fields are, please read the Fields section first.

Parameters

None.

Returns

An array of the fields that exist on all organizations for your team.

Opportunities

An opportunity in Affinity represents a potential future sale or deal for your team. It can have multiple people - your team's main points of contacts for the opportunity - and organization(s) associated with it. Opportunities are generally used to track the progress of and revenue generated from sales and deals in your pipeline with a specific organization.

Unlike people and organizations, an opportunity can only belong to a single list and, thus, does not have global fields. This list must be provided at the creation of the opportunity. If the list or list entry containing the opportunity gets deleted, then the opportunity subsequently gets deleted. If a user does not have permission to access a list with opportunities, the user cannot view any of those opportunities.

The Opportunity Resource

Example Response

{
  "id": 117,
  "name": "Affinity Opportunity",
  "person_ids": [38706],
  "organization_ids": [21442],
  "list_entries": [
    {
      "id": 442313,
      "creator_id": 38706,
      "list_id": 4974,
      "entity_id": 117,
      "entity_type": 8,
      "created_at": "2018-03-03T23:02:46.412-08:00"
    }
  ]
}

Each opportunity object has a unique id. It also has a name, persons_ids and organization_ids associated with it, and an array of list_entries. An important attribute to note is list_entries. Because an opportunity can only belong to a single list, list_entries can only have one list entry.

Of course, all fields can be modified and the opportunity can be deleted.

Search for Opportunities

GET /opportunities

Searches your team's data and fetches all the opportunities that meet the search criteria. The search term can be a part of an opportunity's name.

This result is paginated. An initial request returns an object with two fields: opportunities and next_page_token. opportunities contains an array of opportunity resources. The value of next_page_token should be sent as the query parameter page_token in another request to retrieve the next page of results. While paginating through results, each request must have identical query parameters other than the changing page_token. Otherwise, an Invalid page_token variable error will be returned.

The absence of a next_page_token indicates that all the records have been fetched, though its presence does not necessarily indicate that there are more resources to be fetched. The next page may be empty (but then next_page_token would be null to confirm that there are no more resources).

Example Request

curl "https://api.affinity.co/opportunities?term=affinity" -u :$APIKEY

Example Response

{
  "opportunities": [
    {
      "id": 121,
      "name": "Affinity Opportunity",
      "person_ids": [3526824],
      "organization_ids": [128367168],
      "list_entries": [
        {
          "id": 442313,
          "creator_id": 1124736,
          "list_id": 4974,
          "entity_id": 121,
          "entity_type": 8,
          "created_at": "2018-03-03T23:02:46.412-08:00"
        },
      ],
    },
    {
      "id": 150,
      "name": "Affinity Opportunity 2",
      "person_ids": [5326214],
      "organization_ids": [128367168],
      "list_entries": [
        {
          "id": 442421,
          "creator_id": 1124736,
          "list_id": 4974,
          "entity_id": 150,
          "entity_type": 8,
          "created_at": "2018-03-08T23:02:46.412-08:00"
        },
      ],
    },
    ...
  ],
  "next_page_token": "eyJwYXJhbXMiOnsidGVybSI6IiJ9LCJwYWdlX3NpemUiOjUsIm9mZnNldCI6MTB9",
}

Example pagination

# To get the second page of results, issue the following query:
curl "https://api.affinity.co/opportunities?term=affinity&page_token=eyJwYXJhbXMiOnsidGVybSI6IiJ9LCJwYWdlX3NpemUiOjUsIm9mZnNldCI6MTB9" -u :$APIKEY

Query Parameters

Returns

An object with two fields: opportunities and next_page_token. opportunities maps to an array of all the opportunity resources that match the search criteria. next_page_token includes a token to be sent along with the next request as the page_token parameter to fetch the next page of results.

Get a Specific Opportunity

Example Request

curl "https://api.affinity.co/opportunities/117" -u :$APIKEY

Example Response

{
  "id": 117,
  "name": "Affinity Opportunity",
  "person_ids": [3526824],
  "organization_ids": [128367168],
  "list_entries": [
    {
      "id": 442313,
      "creator_id": 1124736,
      "list_id": 4974,
      "entity_id": 117,
      "entity_type": 8,
      "created_at": "2018-03-03T23:02:46.412-08:00"
    },
  ],
}

GET /opportunities/{opportunity_id}

Fetches an opportunity with a specified opportunity_id.

Path Parameters

Returns

The opportunity object corresponding to the opportunity_id.

Create a New Opportunity

Example Request

curl -X POST "https://api.affinity.co/opportunities" \
   -u :$APIKEY \
   -H "Content-Type: application/json" \
   -d '{"name": "Penny Opportunity", "list_id": 6645, "person_ids": [38706], "organization_ids": [21442]}'

Example Response

{
  "id": 120611418,
  "name": "Penny Opportunity",
  "person_ids": [38706],
  "organization_ids": [21442],
  "list_entries": [
    {
      "id": 999886,
      "creator_id": 1127776,
      "list_id": 6645,
      "entity_id": 50,
      "entity_type": 8,
      "created_at": "2018-03-07T16:32:35.794-08:00"
    }
  ]
}

POST /opportunities

Creates a new opportunity with the supplied parameters.

Payload Parameters

Returns

The opportunity resource that was just created by a successful request (without person_ids and organization_ids).

Update an Opportunity

Example Request

curl -X POST "https://api.affinity.co/opportunities/120611418" \
  -u :$APIKEY \
  -H "Content-Type: application/json" \
  -d '{"name": "Penny Opp", "person_ids": [38706, 89734]}'

Example Response

{
  "id": 120611418,
  "name": "Penny Opp",
  "person_ids": [38706, 89734],
  "organization_ids": [21442],
  "list_entries": [
    {
      "id": 999886,
      "creator_id": 1127776,
      "list_id": 6645,
      "entity_id": 50,
      "entity_type": 8,
      "created_at": "2018-03-07T16:32:35.794-08:00"
    }
  ]
}

PUT /opportunities/{opportunity_id}

Updates an existing opportunity with opportunity_id with the supplied parameters.

Path Parameters

Payload Parameters

Returns

The opportunity resource that was just updated through a successful request.

Delete an Opportunity

Example Request

curl "https://api.affinity.co/opportunities/120611418" \
  -u :$APIKEY \
  -X "DELETE"

Example Response

{ "success": true }

DELETE /opportunities/{opportunity_id}

Deletes an opportunity with a specified opportunity_id.

Path Parameters

Returns

{success: true}.

Interactions

The interactions API allows you to manage interactions.

The Interactions Resource

Different types of interactions have different interaction resources. Note the combination of ID and type for an interaction is unique.

Example Response

# Meeting/Call type
{
    "date": "2022-02-22T11:15:29.758-08:00",
    "id": 3007,
    "attendees": [
        "john@affinity.co",
        "yen@alice.com"
    ],
    "start_time": "2022-02-22T11:15:29.758-08:00",
    "end_time": null,
    "updated_at": null,
    "manual_creator_id": 2,
    "title": "Manually logged event",
    "type": 0,
    "notes": [
        7
    ],
    "persons": [
        {
            "id": 443,
            "type": 1,
            "first_name": "John",
            "last_name": "Doe",
            "primary_email": "john@affinity.co",
            "emails": [
                "john@affinity.co"
            ]
        },
        {
            "id": 2021,
            "type": 0,
            "first_name": "Alice",
            "last_name": "Yen",
            "primary_email": "yen@alice.com",
            "emails": [
                "yen@alice.com"
            ]
        }
    ]
}

# Chat message type
{
    "id": 7267,
    "date": "2022-02-22T11:50:20.126-08:00",
    "direction": 0,
    "manual_creator_id": 443,
    "persons": [
        {
            "id": 443,
            "type": 1,
            "first_name": "John",
            "last_name": "Doe",
            "primary_email": "john@affinity.co",
            "emails": [
                "john@affinity.co"
            ]
        },
        {
            "id": 2021,
            "type": 0,
            "first_name": "Alice",
            "last_name": "Yen",
            "primary_email": "yen@alice.com",
            "emails": [
                "yen@alice.com"
            ]
        }
    ],
    "type": 2,
    "notes": [
        7462534
    ]
}

# Email type
{
    "date": "2021-02-04T09:43:39.717-08:00",
    "id": 417,
    "subject": "John <-> Alice",
    "type": 3,
    "from": {
        "id": 443,
        "type": 1,
        "first_name": "John",
        "last_name": "Doe",
        "primary_email": "john@affinity.co",
        "emails": [
            "john@affinity.co"
        ]
    },
    "to": [
        {
            "id": 2021,
            "type": 0,
            "first_name": "Alice",
            "last_name": "Yen",
            "primary_email": "yen@alice.com",
            "emails": [
                "yen@alice.com"
            ]
        }
    ],
    "cc": [],
    "direction": 0
}

Interactions Types

Direction Types

Logging Types

Get All Interactions

Example Request

curl "https://api.affinity.co/interactions?organization_id=1609909&type=3&start_time=2021-01-01T07:00:00Z&end_time=2021-02-25T21:00:00Z&" -u :$APIKEY

Example Response

{
  "emails": [
    {
      "date": "2021-02-04T09:43:39.717-08:00",
      "id": 417,
      "subject": "John <-> Alice",
      "type": 3,
      "from": {
        "id": 443,
        "type": 1,
        "first_name": "John",
        "last_name": "Doe",
        "primary_email": "john@affinity.co",
        "emails": ["john@affinity.co"]
      },
      "to": [
        {
          "id": 2021,
          "type": 0,
          "first_name": "Alice",
          "last_name": "Yen",
          "primary_email": "yen@alice.com",
          "emails": ["yen@alice.com"]
        }
      ],
      "cc": [],
      "direction": 0
    },
    {
      "date": "2021-02-02T12:55:19.801-08:00",
      "id": 265,
      "subject": "Alfred <-> Alice",
      "type": 3,
      "from": {
        "id": 1012,
        "type": 1,
        "first_name": "Alfred",
        "last_name": "Hickey",
        "primary_email": "alfredhickeyshmcneax@affinity.co",
        "emails": ["alfredhickeyshmcneax@affinity.co"]
      },
      "to": [
        {
          "id": 2021,
          "type": 0,
          "first_name": "Alice",
          "last_name": "Yen",
          "primary_email": "yen@alice.com",
          "emails": ["yen@alice.com"]
        }
      ],
      "cc": [],
      "direction": 0
    }
  ],
  "next_page_token": "eyJwYXJhbXMiOnsiY29tcGxldGVyX2lkIjpudWxsLCJvd25lcl9pZCI6bnVsbCwiY3JlYXRvcl9"
}