NAV Navbar
Logo
shell

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.

Overview

Authentication

Authentication using HTTP basic auth.

curl "https://api.affinity.co/api_endpoint" -u :<API-KEY>

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.

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:

Error Code Meaning
401 Unauthorized – Your API key is invalid.
404 Not Found – Requested resource does not exist.
422 Unprocessable Entity – Malformed parameters supplied. This can also happen in cases the parameters supplied logically cannot complete the request. In this case, an appropriate error message is delivered.
429 Too Many Requests – You have exceed the rate limit.
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – This shouldn’t generally happen. Either a deploy is in process, or Affinity services are down.

Note: Requests must be sent over HTTPS. Requests sent over HTTP will not return any data in order to ensure your sensitive information remains secure.

Rate Limiting

Each API key is limited to 150k requests per day. Once you hit the quota, all further requests will return an error code of 429 - this will reset as soon as the next day begins.

Data Model

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 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” in Affinity, and the value in each cell is represented by a “Field Value”.

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

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.

Attribute Type Description
id integer The unique identifier of the field object.
name string The name of the field.
allows_multiple boolean This determines whether multiple values can be added to a single cell for the field.
dropdown_options object[] Affinity supports pre-entered dropdown options for fields of the “Ranked Dropdown” value_type. The array is empty unless there are valid dropdown options for the field of the “Ranked Dropdown” value type.
value_type integer This field describes what values can be associated with the field. This can be one of many values, as described in the table below.

Field Value Types

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

Note:

The API currently only supports fetching field data for field value creation. It does not support updating, deleting, or creating fields. Modifying or creating an field must be done through the web product.

For accessing person global fields, see the Person Fields endpoint. For accessing organization global fields, see the Organization Fields endpoint. For accessing list specific fields on a list, see the Specific List endpoint.

Value Type Description
0 Person This type enables you to add person objects as a value. Eg: External Source, Owner, Friends
1 Organization This type enables you to add organization objects as a value. Eg: Place of work, Co-Investors
2 Dropdown This type allows you to add a text option into a single cell. This is best used when you want to store information that is unique to a person or organization. Eg: Interests, Stage, Industry
3 Number This type enables you to add number as a value. Eg: Deal Size, Check Size, Revenue
4 Date This type enables you to add date as a value. Eg: Date of Event, Birthday
5 Location This type enables you to add a smart Google Maps location as a value. Eg: Address
6 Text This type enables you to add a long text block as a value. Eg: Summary
7 Ranked Dropdown This type allows you to add values in a particular order as well as assign colors to them. This is the equivalent of a pick list. Eg: Status, Priority, Ranking

Lists

Lists are the primary data structure that you can interact with in Affinity. Each list manages a collection of either people or organizations. We call people or organizations “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, or organization in a list of organizations.

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,
  "list_size": 67
}
Attribute Type Description
id integer The unique identifier of the list object.
type integer The type of the entities contained within the list. A list can contain people or organizations, but not both.
name string The title of the list that is displayed in Affinity.
public boolean If the list is publicly accessible to all users in your team, this is true. Otherwise, this is false.
owner_id integer The unique id of the internal person who created this list.
list_size integer The number of list entries contained within the list.

List types

List Type Value Description
person 0 Type specifying a list of people.
organization 1 Type specifying a list of organizations.

Get all lists

Example Request

# Returns an array of all lists that you have access to.
curl "https://api.affinity.co/lists" -u :<API-KEY>

Example Response

[
  {
    "id": 450,
    "name": "My List of People",
    "type": 0,
  },
  {
    "id": 383,
    "name": "My List of Organizations",
    "type": 1,
  },
  ...
]

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 :<API-KEY>

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

Parameter Type Required Description
list_id integer true The unique id of the list object to be retrieved.

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.

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",
    "phone_numbers": [ ],
    "primary_email": "jdoe@jdoe.com",
    "emails": [
      "jdoe@jdoe.com",
      "jdoe2@jdoe2.com",
    ],
  },
  "created_at": "2017-01-16 16:34:03 -0800"
}

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 or organizations).

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

Note: Although list entries correspond to rows in an Affinity spreadsheet, the values associated with the entity are not stored inside the list entry resource. If you are trying to update, create, or delete a value in one of the custom columns for this list entry, please refer to the Field Values section. The list entry API is only used for getting, adding, or removing entities from a list. It does not handle updating individual cells in columns.

Attribute Type Description
id integer The unique identifier of the list entry object.
list_id integer The unique identifier of the list on which the list entry resides.
creator_id integer The unique identifier of the user who created the list entry. If you create a list entry through the API, the user corresponding to the API token will be the creator by default.
entity_id integer The unique identifier of the entity corresponding to the list entry.
entity object Object containing entity-specific details like name, email address, domain etc. for the entity corresponding to entity_id.
created_at datetime The time when the list entry was created.

Get all list entries

Example Request

curl "https://api.affinity.co/lists/450/list-entries" -u :<API-KEY>

Example Response

[
  {
    "id": 64608,
    "list_id": 222,
    "creator_id": 287843,
    "entity_id": 62034,
    "created_at": "2017-05-04 10:44:31 -0700",
    "entity": {
      "type": 0,
      "first_name": "Affinity",
      "last_name": "Team",
      "phone_numbers": [ ],
      "primary_email": "team@affinity.co",
      "emails": [
        "team@affinity.co"
      ],
    },
  },
  {
    "id": 53510,
    "list_id": 222,
    "creator_id": 38596,
    "entity_id": 241576,
    "created_at": "2017-02-22 15:22:21 -0800",
    "entity": {
      "type": 0,
      "first_name": "John",
      "last_name": "Doe",
      "phone_numbers": [ ],
      "primary_email": "jdoe@stanford.edu",
      "emails": [
        "jdoe@stanford.edu"
      ],
    },
  },
  ...
]

GET /lists/{list_id}/list-entries

Fetches all the list entries in the list with the supplied list id.

Path Parameters

Parameter Type Required Description
list_id integer true The unique id of the list whose list entries are to be retrieved.

Returns

An array of all the list entry resources corresponding to the provided list. Each list entry in the array 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 :<API-KEY>

Example Response

{
  "id": 53510,
  "list_id": 222,
  "creator_id": 38596,
  "entity_id": 241576,
  "created_at": "2017-02-22 15:22:21 -0800",
  "entity": {
    "type": 0,
    "first_name": "John",
    "last_name": "Doe",
    "phone_numbers": [ ],
    "primary_email": "jdoe@stanford.edu",
    "emails": [
      "jdoe@stanford.edu"
    ],
  },
}

Path Parameters

Parameter Type Required Description
list_id integer true The unique id of the list that contains the specified list_entry_id.
list_entry_id integer true The unique id of the list entry object to be retrieved.

Returns

The list entry object corresponding to the list_entry_id.

Create a new list entry

Example Request

curl "https://api.affinity.co/lists/450/list-entries" \
   -u :<API-KEY> \
   -d entity_id=38706

Example Response

{
  "id": 53510,
  "list_id": 222,
  "creator_id": 38596,
  "entity_id": 241576,
  "created_at": "2017-02-22 15:22:21 -0800",
  "entity": {
    "type": 0,
    "first_name": "John",
    "last_name": "Doe",
    "phone_numbers": [ ],
    "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.

Note: A list can contain the same entity multiple times. Depending on your use case, before you add an entry, you might want to make sure that it does not exist in the list already.

Path Parameters

Parameter Type Required Description
list_id integer true The unique id of the list whose list entries are to be retrieved.
entity_id integer true The unique id of the entity (person, organization, or opportunity) to add to this list.
creator_id integer false 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.

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 :<API-KEY> \
   -d entity_id=38706 \
   -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.

Note:

  1. This will also delete all the field values, if any, associated with the list entry. Such field values will only exist in fields specific to this list.
  2. If the list entry belongs to an Opportunity list, then the opportunity that the list entry is associated with will also be deleted.

Path Parameters

Parameter Type Required Description
list_id integer true The unique id of the list that contains the specified list_entry_id.
list_entry_id integer true The unique id of the list entry object to be deleted.

Returns

The JSON object {"success": true}.

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.

Note:

  1. If you are looking to add or remove a person from a list, please check out the List Entries section of the API.
  2. If you are looking to modify a person’s field values (one of the cells on Affinity’s spreadsheet), please check out the Field Values section of the API.

The person resource

Example Response

{
  "id": 38706,
  "type": 0,
  "first_name": "John",
  "last_name": "Doe",
  "phone_numbers": ["123-456-7890"],
  "primary_email": "john@affinity.co",
  "emails": [
    "john@affinity.co",
    "john@affinity.co",
    "jdoe@alumni.stanford.edu",
    "johnjdoe@gmail.com",
  ],
  "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_interaction_date": "2012-03-04T05:06:07.890-08:00",
    "next_event_date": "2019-03-04T05:06:07.890-08:00",
  },
},

Each person resource is assigned a unique id and stores the name, phone numbers, 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.

Attribute Type Description
id integer The unique identifier of the person object.
type integer The type of person (see below).
first_name string The first name of the person.
last_name string The last name of the person.
emails string[] The email addresses of the person.
phone_numbers string[] The phone numbers of the person.
primary_email string The email (automatically computed) that is most likely to the current active email address of the person.
organization_ids integer[] An array of unique identifiers of organizations that the person is associated with.
list_entries ListEntry[] An array of list entry resources associated with the person, only returned as part of the Get a specific person endpoint.
interaction_dates object An object with four string date fields representing the most recent and upcoming interactions with this person: first_email_date, last_email_date, last_event_date, last_interacton_date and next_event_date. Only returned when passing with_interaction_dates=true.

Person types

Type Value Description
external 0 Default value. All people that your team has spoken with externally have this type.
internal 1 All people on your team that have Affinity accounts will have this type.

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.

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 :<API-KEY>

Example Response

{
  "persons": [
    {
      "id": 38706,
      "type": 0,
      "first_name": "John",
      "last_name": "Doe",
      "phone_numbers": ["123-456-7890"],
      "primary_email": "john@affinity.co",
      "emails": [
        "john@affinity.co",
        "john@affinity.co",
        "jdoe@alumni.stanford.edu",
        "johnjdoe@gmail.com",
      ]
    },
    {
      "id": 624289,
      "type": 1,
      "first_name": "Jane",
      "last_name": "Doe",
      "phone_numbers": ["098-765-4321"],
      "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 :<API-KEY>

Query Parameters

Parameter Type Required Description
term string true 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 false When true, interaction dates will be present on the returned resources. Only persons that have interactions will be returned.
{min,max}_<interaction>_date string false Only returns persons with the given interaction type above or below the given value. interaction can be one of first_email, last_email, last_interaction, last_event, or next_event.
page_size number false How many results to return per page. (Default is the maximum value of 500.)
page_token string false The next_page_token from the previous response required to retrieve the next page of results.

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" -u :<API-KEY>

Example Response

{
  "id": 38706,
  "type": 0,
  "first_name": "John",
  "last_name": "Doe",
  "phone_numbers": ["123-456-7890"],
  "primary_email": "john@affinity.co",
  "emails": [
    "john@affinity.co",
    "john@affinity.co",
    "jdoe@alumni.stanford.edu",
    "johndoe@gmail.com",
  ],
  "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

Parameter Type Required Description
person_id integer true The unique id of the person that needs to be retrieved.
with_interaction_dates boolean false When true, interaction dates will be present on the returned resources.

Returns

The person resource corresponding to the person_id.

Create a new person

Example Request

curl "https://api.affinity.co/persons" \
  -u :<API-KEY> \
  -d first_name="Alice" \
  -d last_name="Doe" \
  -d emails[]="alice@affinity.co" \
  -d phone_numbers[]="123-123-123" \
  -d organization_ids[]=1687449

Example Response

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

POST /persons

Creates a new person with the supplied parameters.

Note:

  1. If one of the supplied email addresses conflicts with another person object, this request will fail and an appropriate error will be returned.
  2. If you are looking to add an existing person to a list, please check the List Entries section of the API.

Payload Parameters

Parameter Type Required Description
first_name string true The first name of the person.
last_name string true The last name of the person.
emails string[] true The email addresses of the person. If there are no email addresses, please specify an empty array.
phone_numbers string[] false The phone numbers of the person. If there are no phone numbers, please specify an empty array.
organization_ids integer[] false An array of unique identifiers of organizations that the person is associated with.

Returns

The person resource was newly created from this successful request.

Update a person

Example Request

curl "https://api.affinity.co/860197" \
  -u :<API-KEY> \
  -d phone_numbers[]="123-123-123" \
  -d phone_numbers[]="234-234-234" \
  -d first_name="Allison" \
  -X "PUT"

Example Response

{
  "id":860197,
  "type":0,
  "first_name":"Allison",
  "last_name":"Doe",
  "phone_numbers":["123-123-123","234-234-234"],
  "primary_email":"alice@affinity.co",
  "emails":["alice@affinity.co"],
  "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.

Note:

If you are looking to add an existing person to a list, please check the List Entries section of the API.

If you are trying to add a new phone number, email, or organization to a person, the existing values for phone_numbers, emails and organization_ids must also be supplied as parameters.

Path Parameters

Parameter Type Required Description
person_id integer true The unique id of the person that needs to be retrieved.

Payload Parameters

Parameter Type Required Description
first_name string false The first name of the person.
last_name string false The last name of the person.
emails string[] false The email addresses of the person. If there are no email addresses, please specify an empty array.
phone_numbers string[] false The phone numbers of the person. If there are no phone numbers, please specify an empty array.
organization_ids integer[] false An array of unique identifiers of organizations that the person is associated with

Returns

The person object that was just updated through this request.

Delete a person

Example Request

curl "https://api.affinity.co/persons/860197" \
  -u :<API-KEY> \
  -X "DELETE"

Example Response

{"success": true}

DELETE /persons/{person_id}

Deletes a person with a specified person_id.

Note: This will also delete all the field values, if any, associated with the person. Such field values exist linked to either global or list-specific fields.

Path Parameters

Parameter Type Required Description
person_id integer true The unique id of the person that needs to be deleted.

Returns

{success: true}.

Get global 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 :<API-KEY>

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.

Relationship Strengths

Affinity calculates relationship strengths between internal and external people based on previous interactions (emails, logged calls, calendar events).

A higher numeric value means that the relationship strength between the two people is higher. Emails, calls, and meetings don’t tell the whole story of a relationship, so treat the strength as an estimate.

Relationship strengths are usually recalculated daily.

The relationship strength resource

Example Response

{
  "external_id": 1234,
  "internal_id": 2345,
  "strength": 0.5,
}

The relationship strength resource specifies the two Persons the relationship strength is about, along with the actual value.

There may be at most one resource for every (internal, external) pair. If an internal and external person have no previous interactions, there may be no relationship strength resource for the pair.

Attribute Type Description
internal_id integer The internal person associated with this relationship strength.
external_id integer The external person associated with this relationship strength.
strength float The actual relationship strength. This is currently a number between 0 and 1, but may change in the future.

Fetch a relationship strength

GET /relationship-strengths

Example Request

# Returns an array relationship strengths matching the criteria.
curl "https://api.affinity.co/relationships-strengths?external_id=1234&internal_id=2345" -u :<API-KEY>

Example Response

[
  {
    "internal_id": 1234,
    "external_id": 2345,
    "strength": 0.5,
  }
]

Example Request

# Returns an array relationship strengths matching the criteria.
curl "https://api.affinity.co/relationships-strengths?external_id=1234" -u :<API-KEY>

Example Response

[
  {
    "external_id": 1234,
    "internal_id": 2345,
    "strength": 0.5,
  },
  {
    "external_id": 1234,
    "internal_id": 3456,
    "strength": 0.9,
  },
  ...
]

Query Parameters

Parameter Type Required Description
internal_id integer false The internal person associated with this relationship strength.
external_id integer true The external person associated with this relationship strength.

Returns

An array of the relationship strengths matching the criteria.

If an internal_id is given, returns the relationship strength between the given internal and external person. The returned list will have a length of 1 or 0 (if no relationship strength is available between the two people).

If no internal_id is given, returns the relationship strengths between all internal people and the given external person. The results are not guaranteed to be sorted in any way.

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.

Note:

  1. If you are looking to add or remove an organization from a list, please check out the List Entries section of the API.
  2. If you are looking to modify a field value (one of the cells on Affinity’s spreadsheet), please check out the Field Values section of the API.

The organization resource

Example Response

{
  "id":64779194,
  "name":"Affinity",
  "domain":"affinity.co",
  "crunchbase_uuid":"ca0e6bd5-7de2-0a26-f648-0bf66e88b05c",
  "global":false,
  "person_ids":[89734, 117270, 138123, 274492, 304848, ...]
  "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_interaction_date": "2012-03-04T05:06:07.890-08:00",
    "next_event_date": "2019-03-04T05:06:07.890-08:00",
  },
}

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 /organizations or the /organizations/{organization_id} endpoints.

Attribute Type Description
id integer The unique identifier of the organization object.
name integer The name of the organization (see below).
domain string The website name of the organization. This is used by Affinity to automatically associate person objects with an organization.
crunchbase_uuid string The Crunchbase UUID of the organization
person_ids string[] An array of unique identifiers of person that are associated with the organization
global boolean Returns whether this organization is a part of Affinity’s global dataset of organizations. This is always false if the organization was created by you.
list_entries ListEntry[] An array of list entry resources associated with the organization, only returned as part of the Get a specific organization endpoint.
interaction_dates object An object with four string date fields representing the most recent and upcoming interactions with this organization: first_email_date, last_email_date, last_event_date, last_interacton_date and next_event_date. Only returned when passing with_interaction_dates=true.

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.

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/organizations?term=affinity" -u :<API-KEY>

Example Response

{
  "organizations": [
    {
      "id":64779194,
      "name":"Affinity",
      "domain":"affinity.co",
      "crunchbase_uuid":null,
      "global":false
    },
    {
      "id":1513682,
      "name":"Brand Affinity Technologies",
      "domain":"brandaffinity.net",
      "crunchbase_uuid":"035ed4bb-7a8c-f713-5032-91a81a4b4bb9",
      "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?term=affinity&page_token=eyJwYXJhbXMiOnsidGVybSI6IiJ9LCJwYWdlX3NpemUiOjUsIm9mZnNldCI6MTB9" -u :<API-KEY>

Query Parameters

Parameter Type Required Description
term string false A string used to search all the organizations in your team’s address book. This could be a name or a domain name.
with_interaction_dates boolean false When true, interaction dates will be present on the returned resources. Only organizations that have interactions will be returned.
{min,max}_<interaction>_date string false Only returns organizations with the given interaction type above or below the given value. interaction can be one of first_email, last_email, last_interaction, last_event, or next_event.
page_size number false How many results to return per page. (Default is the maximum value of 500.)
page_token string false The next_page_token from the previous response required to retrieve the next page of results.

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 :<API-KEY>

Example Response

{
  "id":64779194,
  "name":"Affinity",
  "domain":"affinity.co",
  "crunchbase_uuid":"ca0e6bd5-7de2-0a26-f648-0bf66e88b05c",
  "global":false,
  "person_ids":[89734, 117270, 138123, 274492, 304848, ...],
  "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

Parameter Type Required Description
organization_id integer true The unique id of the organization that needs to be retrieved.
with_interaction_dates boolean false When true, interaction dates will be present on the returned resources.

Returns

The organization object corresponding to the organization_id.

Create a new organization

Example Request

curl "https://api.affinity.co/organizations" \
  -u :<API-KEY> \
  -d name="Acme Corporation" \
  -d domain="acme.co" \
  -d person_ids[]=38706

Example Response

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

POST /organizations

Creates a new organization with the supplied parameters.

Note: If you are looking to add an existing organization to a list, please check the List Entries section of the API.

Payload Parameters

Parameter Type Required Description
name string true The name of the organization.
domain string false The domain name of the organization.
person_ids integer[] false An array of unique identifiers of persons that the new organization will be associated with.

Returns

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

Update an organization

Example Request

curl "https://api.affinity.co/organizations/120611418" \
  -u :<API-KEY> \
  -d name="Acme Corp." \
  -d person_ids[]=38706 \
  -d person_ids[]=89734 \
  -X "PUT"

Example Response

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

PUT /organizations/{organization_id}

Updates an existing organization with organization_id with the supplied parameters.

Note:

If you are looking to add an existing organization to a list, please check the List Entries section of the API.

If you are trying to add a person to an organization, the existing values for person_ids must also be passed into the endpoint.

Path Parameters

Parameter Type Required Description
organization_id integer true The unique id of the organization to be updated.

Payload Parameters

Parameter Type Required Description
name string false The name of the organization.
domain string false The domain name of the organization.
person_ids integer[] false An array of unique identifiers of persons that the organization will be associated with.

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 :<API-KEY> \
  -X "DELETE"

Example Response

{"success": true}

DELETE /organizations/{organization_id}

Deletes an organization with a specified organization_id.

Note:

  1. An appropriate error will be returned if you are trying to delete a global organization.
  2. This will also delete all the field values, if any, associated with the organization. Such field values exist linked to either global or list-specific fields.

Path Parameters

Parameter Type Required Description
organization_id integer true The unique id of the organization that needs to be deleted.

Returns

{success: true}.

Get global fields

Example Request

curl "https://api.affinity.co/organizations/fields" -u :<API-KEY>

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.

Note:

  1. If you are looking to remove an opportunity from a list, note that deleting an opportunity is the same as removing an opportunity from a list because an opportunity can only exist on a single list with a single list entry.
  2. If you are looking to modify a field value (one of the cells on Affinity’s spreadsheet), please check out the Field Values section of the API.

The opportunity resource

Example Response

{
  "id":117,
  "name":"Affinity Opp",
  "person_ids":[38706],
  "organization_ids":[21442],
  "list_entries": [
    {
      "id":442313,
      "creator":{
        "id":38706,
        "type":1,
        "emails": ["john@affinity.co", "johnjdoe@gmail.com"],
        "firstName":"John",
        "lastName":"Doe",
        "photoUrl":"https://dapjjo8h3d36y.cloudfront.net/315dc7f40516f732ds9b817a03f6d826e",
        "entityType":0,
        "inferredType":1,
        "interactionsHidden":true,
        "hiddenExternal":false,
        "primaryEmail":"john@affinity.co"
      },
      "listId":4974,
      "entityId":117,
      "createdAt":"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.

Attribute Type Description
id integer The unique identifier of the opportunity object.
name integer The name of the opportunity (see below).
person_ids number[] An array of unique identifiers for persons that are associated with the opportunity
organization_ids number[] An array of unique identifiers for organizations that are associated with the opportunity
list_entries ListEntry[] An array of list entry resources associated with the opportunity (at most 1 list entry). If the

user corresponding to the API key does not have access to the list, this will be empty.

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 :<API-KEY>

Example Response

{
  "opportunities": [
    {
      "id":121,
      "name":"Affinity Opp",
      "person_ids":[3526824],
      "organization_ids":[128367168],
      "list_entries": [
        {
          "id":442313,
          "creator":{
            "id":1124736,
            "type":1,
            "emails": ["john@affinity.co", "johnjdoe@gmail.com"],
            "firstName":"John",
            "lastName":"Doe",
            "photoUrl":"https://dapjjo8h3d36y.cloudfront.net/315dc7f40516f732ds9b817a03f6d826e",
            "entityType":0,
            "inferredType":1,
            "interactionsHidden":true,
            "hiddenExternal":false,
            "primaryEmail":"john@affinity.co"
          },
        "listId":4974,
        "entityId":121,
        "createdAt":"2018-03-03T23:02:46.412-08:00"
        },
      ],
    }
    {
      "id":150,
      "name":"Affinity Opp 2",
      "person_ids":[5326214],
      "organization_ids":[128367168],
      "list_entries": [
        {
          "id":442421,
          "creator":{
            "id":1124736,
            "type":1,
            "emails": ["john@affinity.co", "johnjdoe@gmail.com"],
            "firstName":"John",
            "lastName":"Doe",
            "photoUrl":"https://dapjjo8h3d36y.cloudfront.net/315dc7f40516f732ds9b817a03f6d826e",
            "entityType":0,
            "inferredType":1,
            "interactionsHidden":true,
            "hiddenExternal":false,
            "primaryEmail":"john@affinity.co"
          },
        "listId":4974,
        "entityId":150,
        "createdAt":"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 :<API-KEY>

Query Parameters

Parameter Type Required Description
term string false A string used to search all the opportunities in your team’s database. This could be part of a name.
page_size number false How many results to return per page. (Default is the maximum value of 500.)
page_token string false The next_page_token from the previous response required to retrieve the next page of results.

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 :<API-KEY>

Example Response

{
  "id":121,
  "name":"Affinity Opp",
  "person_ids":[3526824],
  "organization_ids":[128367168],
  "list_entries": [
    {
      "id":442313,
      "creator": {
        "id":1124736,
        "type":1,
        "emails": ["john@affinity.co", "johnjdoe@gmail.com"],
        "firstName":"John",
        "lastName":"Doe",
        "photoUrl":"https://dapjjo8h3d36y.cloudfront.net/315dc7f40516f732ds9b817a03f6d826e",
        "entityType":0,
        "inferredType":1,
        "interactionsHidden":true,
        "hiddenExternal":false,
        "primaryEmail":"john@affinity.co"
      },
      "listId":4974,
      "entityId":121,
      "createdAt":"2018-03-03T23:02:46.412-08:00"
    },
  ],
}

GET /opportunities/{opportunity_id}

Fetches an opportunity with a specified opportunity_id.

Path Parameters

Parameter Type Required Description
opportunity_id integer true The unique id of the opportunity that needs to be retrieved.

Returns

The opportunity object corresponding to the opportunity_id.

Create a new opportunity

Example Request

curl "https://api.affinity.co/opportunities" \
  -u :<API-KEY> \
  -d name="Penny Opportunity" \
  -d list_id=6645 \
  -d person_ids[]=38706 \
  -d organization_ids[]=21442

Example Response

{
  "id":50,
  "name":"Penny Opportunity",
  "person_ids":[38706],
  "organization_ids":[21442],
  "list_entries": [
    {
      "id":999886,
      "creator": {
        "id":1127776,
        "type":1,
        "emails":["john@affinity.co", "john@berkeley.edu"],
        "firstName":"John",
        "lastName":"Doe",
        "photoUrl":"https://dapjjo8h3d36y.cloudfront.net/315dc7f40516f73259b807a06f6d826a",
        "entityType":0,
        "inferredType":1,
        "interactionsHidden":true,
        "hiddenExternal":false,
        "primaryEmail":"john@affinity.co"
      },
      "listId":6645,
      "entityId":50,
      "createdAt":"2018-03-07T16:32:35.794-08:00"
    },
  ]
}

POST /opportunities

Creates a new opportunity with the supplied parameters.

Payload Parameters

Parameter Type Required Description
name string true The name of the opportunity.
list_id integer true An unique identifier of the list that the new opportunity will be associated with. This list must be of type opportunity.
person_ids integer[] false An array of unique identifiers of persons that the new opportunity will be associated with.
organization_ids integer[] false An array of unique identifiers of organizations that the new opportunity will be associated with.

Returns

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

Update an opportunity

Example Request

curl "https://api.affinity.co/opportunities/120611418" \
  -u :<API-KEY> \
  -d name="Penny Opp" \
  -d person_ids[]=38706 \
  -d person_ids[]=89734 \
  -X "PUT"

Example Response

{
  "id":50,
  "name":"Penny Opp",
  "person_ids":[38706,89734],
  "organization_ids":[21442],
  "list_entries": [
    {
      "id":999886,
      "creator": {
        "id":1127776,
        "type":1,
        "emails":["john@affinity.co", "john@berkeley.edu"],
        "firstName":"John",
        "lastName":"Doe",
        "photoUrl":"https://dapjjo8h3d36y.cloudfront.net/315dc7f40516f73259b807a06f6d826a",
        "entityType":0,
        "inferredType":1,
        "interactionsHidden":true,
        "hiddenExternal":false,
        "primaryEmail":"john@affinity.co"
      },
      "listId":6645,
      "entityId":50,
      "createdAt":"2018-03-07T16:32:35.794-08:00"
    }
  ]
}

PUT /opportunities/{opportunity_id}

Updates an existing opportunity with opportunity_id with the supplied parameters.

Note:

If you are trying to add a person to an opportunity, the existing values for person_ids must also be passed into the endpoint.

If you are trying to add an organization to an opportunity, the existing values for organization_ids must also be passed into the endpoint.

Path Parameters

Parameter Type Required Description
opportunity_id integer true The unique id of the opportunity to be updated.

Payload Parameters

Parameter Type Required Description
name string false The name of the opportunity.
person_ids integer[] false An array of unique identifiers of persons that the opportunity will be associated with.
organization_ids integer[] false An array of unique identifiers of organizations that the opportunity will be associated with.

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 :<API-KEY> \
  -X "DELETE"

Example Response

{"success": true}

DELETE /opportunities/{opportunity_id}

Deletes an opportunity with a specified opportunity_id.

Note:

  1. This will also delete all the field values, if any, associated with the opportunity.

Path Parameters

Parameter Type Required Description
opportunity_id integer true The unique id of the opportunity that needs to be deleted.

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.

Note:

By default, Affinity creates some fields for you automatically. These include Location, Industry, Job Titles, and more.

The field value resource

Example Response

# Global Location Field Value
{
  "id":250616,
  "field_id":337,
  "list_entry_id":null,
  "entity_id":38706,
  "value":{
    "city":"San Francisco",
    "state":"California",
    "country":"United States",
    "continent":null,
    "street_address":null
  }
}

# List Specific Dropdown Field Value
{
  "id":177634,
  "field_id":751,
  "list_entry_id":605,
  "entity_id":38706,
  "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.

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

Attribute Type Description
id integer The unique identifier of the field value object.
field_id integer The unique identifier of the field the value is associated with.
entity_id integer The unique identifier of the person, organization, or opportunity object the field value is associated with.
list_entry_id integer The unique identifier of the list entry object the field value is associated with. This only exists if the field the value is associated with is list-specific.
value One of many The value attribute can take on many different types, depending on the field value_type. See below for reference.

Field Value value types

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

Value Type Type Description
dropdown string This represents a value in a dropdown field.
number integer This represents a value in a number field.
person integer This represents a value in a person field.
organization integer This represents a value in an organization field.
location object This represents a value in a location field - it’s an object comprising the following keys: street_address, city, state, country, all of which take string values.
date datetime This represents a value in a date field.
text string This represents a value in a text field.

Get field values

Example Request

curl "https://api.affinity.co/field-values?person_id=38706" -u :<API-KEY>

Example Response

[
  {
    "id":250616,
    "field_id":337,
    "list_entry_id":null,
    "entity_id":38706,
    "value":{
      "city":"San Francisco",
      "state":"California",
      "country":"United States",
      "continent":null,
      "street_address":null
    }
  },
  {
    "id":250615,
    "field_id":1284,
    "list_entry_id":null,
    "entity_id":38706,
    "value":"Computer Software"
  },
  {
    "id":32760,
    "field_id":198,
    "list_entry_id":null,
    "entity_id":38706,
    "value":38659
  },
  {
    "id":177634,
    "field_id":751,
    "list_entry_id":605,
    "entity_id":38706,
    "value":{
      "id":71,
      "text":"Low",
      "rank":1,
      "color":4
    }
  },
  ...
]

GET /field-values

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

Query Parameters

Parameter Type Required Description
person_id integer custom* A unique id that represents a person object whose field values are to be retrieved.
organization_id integer custom* A unique id that represents an organization object whose field values are to be retrieved.
opportunity_id integer custom* A unique id that represents an opportunity object whose field values are to be retrieved.
list_entry_id integer custom* A unique id that represents a list entry object whose field values are to be retrieved.

Note:

  1. custom*: Only one of person_id, organization_id, opportunity_id, or list_entry_id can be specified to the endpoint.
  2. If a person_id, organization_id, or opportunity_id is specified, the endpoint returns all field values tied to these entities - including those that are associated with all list entries that exist for the given person or organization. Opportunities can only have one list entry.

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 "https://api.affinity.co/field-values" \
  -u :<API-KEY> \
  -d field_id=1284 \
  -d value="Architecture" \
  -d entity_id=38706

Example Response

{
  "id":20406836,
  "field_id":1284,
  "list_entry_id":null,
  "entity_id":38706,
  "value":"Architecture"
}

POST /field-values

Creates a new field value with the supplied parameters.

Payload Parameters

Parameter Type Required Description
field_id integer true The unique identifier of the field (column) that the field value is associated with.
entity_id integer true The unique identifier of the entity (person, organization, or opportunity) that the field value is associated with.
list_entry_id integer false The unique identifier of the list entry (list row) that the field value is associated with. Only specify the list_entry_id if the field that the field value is associated with is list specific.
value custom true See the field value resource section for all value types. The value specified must correspond to the value_type of the supplied field.

Returns

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

Update a field value

Example Request

curl "https://api.affinity.co/field-values/20406836" \
  -u :<API-KEY> \
  -d value="Healthcare" \
  -X "PUT"

Example Response

{
  "id":20406836,
  "field_id":1284,
  "list_entry_id":null,
  "entity_id":38706,
  "value":"Healthcare"
}

PUT /field-values/{field_value_id}

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

Note:

If you are looking to add an existing organization to a list, please check the List Entries section of the API.

Path Parameters

Parameter Type Required Description
field_value_id integer true The unique id of the field value that needs to be updated.

Payload Parameters

Parameter Type Required Description
value custom true See the field value resource section for all value types. The value specified must correspond to the value_type of the supplied field.

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 :<API-KEY> \
  -X "DELETE"

Example Response

{"success": true}

DELETE /field-values/{field_value_id}

Deletes an field value with the specified field_value_id.

Path Parameters

Parameter Type Required Description
field_value_id integer true The unique id of the field value that needs to be deleted.

Returns

{success: true}.

Notes

Example Response

{
  "id":22984,
  "creator_id":860197,
  "person_ids":[38706,89734],
  "organization_ids":[64779194],
  "opportunity_ids":[117],
  "content":"Had a lunch meeting with Jane and John today. They are looking to invest.",
  "created_at":"2017-03-28 00:38:41 -0700"
}

Just like field values, notes are used to keep track of state on an entity. They could be notes manually taken from due diligence, a meeting, or a call. Or, notes could be used to store logged activity from a prospect’s visit to your website.

The note resource

A note object contains content, which is a string containing the note body. In addition, a note can be associated with multiple people, organizations, or opportunities. Each person, organization, or opportunity will display linked notes on their profiles.

Attribute Type Description
id integer The unique identifier of the note object.
creator_id integer The unique identifier of the person object who created the note.
person_ids integer[] An array of unique identifiers of person objects that are associated with the note.
organization_ids integer[] An array of unique identifiers of organization objects that are associated with the note.
opportunity_ids integer[] An array of unique identifiers of opportunity objects that are associated with the note.
content string The string containing the content of the note.
created_at datetime The string representing the time when the note was created.

Create a new note

Example Request

curl "https://api.affinity.co/notes" \
  -u :<API-KEY> \
  -d person_ids[]=38706 \
  -d person_ids[]=624289 \
  -d organization_ids[]=120611418 \
  -d opportunity_ids[]=167 \
  -d content="Had a lunch meeting with Jane and \
              John today. They want to invest in \
              Acme Corp."

Example Response

{
  "id":22984,
  "creator_id":860197,
  "person_ids":[38706,89734],
  "organization_ids":[64779194],
  "opportunity_ids":[117],
  "content":"Had a lunch meeting with Jane ... ",
  "created_at":"2017-03-28 00:38:41 -0700"
}

POST /notes

Creates a new note with the supplied parameters.

Affinity’s Gmail Chrome Extension allows users to save an email as a note in Affinity. This same functionality is exposed in our API via the gmail_id parameter. Passing in the id of a Gmail message will automatically sync the email to Affinity (if it hasn’t synced with Affinity already) and associate it with the newly created note. (Make sure that Affinity has access to the account that owns the Gmail mesage.) A note associated with an email cannot have any content.

Path Parameters

Parameter Type Required Description
person_ids integer[] false An array of unique identifiers of person objects that are associated with the new note.
organization_ids integer[] false An array of unique identifiers of organization objects that are associated with the new note.
opportunity_ids integer[] false An array of unique identifiers of opportunity objects that are associated with the new note.
content string false The string containing the content of the new note.
gmail_id string false The id of a Gmail message to save as the content of the note.
creator_id integer false The id of a Person resource who should be recorded as the author of the note. Must be a person who can access Affinity. If not provided the creator defaults to the owner of the API key.
created_at datetime false A string (formatted according to ISO 8601) representing the creation time to be recorded for the note. If not provided, defaults to the current time.

Note that either content or gmail_id must be specified.

Returns

The note resource created through this request.

Entity Files

Entity files are files uploaded to a relevant entity. Possible files, for example, would be a pitch deck for an opportunity or a physical mail correspondence for a person.

Upload files

Example Request

curl "https://api.affinity.co/entity-files" \
  -u :<API-KEY> \
  -F files[]=@Pitch.pdf \
  -F files[]=@10_01_18_meeting.txt \
  -F person_id=4113456

Example Response

{"success": true}

POST /entity-files

Uploads files attached to the entity with the given id.

The file will display on the entity’s profile, provided that the entity is not a person internal to the user’s organization.

Path Parameters

Parameter Type Required Description
file File false A singular file to be uploaded, formatted as form data (multipart/form-data).
files File[] false An array of files to be uploaded, formatted as form data (multipart/form-data).
person_id integer false The unique identifier of the person object to attach the file(s) to.
organization_id integer false The unique identifier of the organization object to attach the file(s) to.
opportunity_id integer false The unique identifier of the opportunity object to attach the file(s) to.

Note:

  1. Files must be attached to a single entity, specified using one of the three entity id parameters (person_id, organization_id, and opportunity_id).
  2. At least one file must be uploaded using the file or files parameters.

Returns

{"success": true}

Additional Materials

SDK and Native Client support

We currently don’t have native clients or SDKs for different languages, but given the rise in the number of REST clients for different languages, we have compiled some resources to make the API super easy to implement for your use case.

Here are some links to REST clients in the most popular languages:

  1. Ruby
  2. Python
  3. Javascript
  4. Go