Affinity logo

persons

Operations about persons

Get all Persons

Paginate through Persons in Affinity. Returns basic information and non-list-specific field data on each Person.

To retrieve field data, you must use either the fieldIds or the fieldTypes parameter to specify the Fields for which you want data returned. These Field IDs and Types can be found using the GET /v2/persons/fields endpoint. When no fieldIds or fieldTypes are provided, Persons will be returned without any field data attached. To supply multiple fieldIds or fieldTypes parameters, generate a query string that looks like this: ?fieldIds=field-1234&fieldIds=affinity-data-location or ?fieldTypes=enriched&fieldTypes=global.

Requires the "Export All People directory" permission.

SecuritybearerAuth
Request
query Parameters
cursor
string

Cursor for the next or previous page

Example: cursor=ICAgICAgYmVmb3JlOjo6Nw
limit
integer <int32> [ 1 .. 100 ]
Default: 100

Number of items to include in the page

Example: limit=100
ids
Array of integers <int64>

People IDs

Example: ids=1&ids=2
fieldIds
Array of strings

Field IDs for which to return field data

Example: fieldIds=field-1&fieldIds=field-2
fieldTypes
Array of strings

Field Types for which to return field data

Items Enum: "enriched" "global" "relationship-intelligence"
Example: fieldTypes=enriched&fieldTypes=global
Responses
200

OK

Response Headers
X-Ratelimit-Limit-User
integer

Number of requests allowed per minute for the user

X-Ratelimit-Limit-User-Remaining
integer

Number of requests remaining for the user

X-Ratelimit-Limit-User-Reset
integer

Time in seconds before the limit resets for the user

X-Ratelimit-Limit-Org
integer

Number of requests allowed per month for the account

X-Ratelimit-Limit-Org-Remaining
integer

Number of requests remaining for the account

X-Ratelimit-Limit-Org-Reset
integer

Time in seconds before the limit resets for the account

Response Schema: application/json
required
Array of objects (Person) <= 100 items

A page of Person results

Array (<= 100 items)
id
required
integer <int64> [ 1 .. 9007199254740991 ]

The persons's unique identifier

firstName
required
string

The person's first name

lastName
required
string or null

The person's last name

primaryEmailAddress
required
string or null <email>

The person's primary email address

emailAddresses
required
Array of strings <email>

All of the person's email addresses

type
required
string

The person's type

Enum: "internal" "external"
Array of objects (Field)

The fields associated with the person

required
object (Pagination)
prevUrl
string or null <uri>

URL for the previous page

nextUrl
string or null <uri>

URL for the next page

400

Bad Request

403

Forbidden

default

Errors

get/v2/persons
Request samples 
Response samples 
application/json
{
  • "pagination": {},
  • "data": [
    ]
}
Get metadata on Person Fields
Returns metadata on non-list-specific Person Fields.


Use the returned Field IDs to request field data from the GET /v2/persons and GET /v2/persons/{id} endpoints.


SecuritybearerAuth 
Request 
query Parameters
cursor
string
Cursor for the next or previous page


 
limit
integer <int32>   [ 1 .. 100 ] 
 Default:  100
Number of items to include in the page


 
 Example:  limit=100
Responses 
200
OK


 Response Headers 
X-Ratelimit-Limit-User
integer
Number of requests allowed per minute for the user


 
X-Ratelimit-Limit-User-Remaining
integer
Number of requests remaining for the user


 
X-Ratelimit-Limit-User-Reset
integer
Time in seconds before the limit resets for the user


 
X-Ratelimit-Limit-Org
integer
Number of requests allowed per month for the account


 
X-Ratelimit-Limit-Org-Remaining
integer
Number of requests remaining for the account


 
X-Ratelimit-Limit-Org-Reset
integer
Time in seconds before the limit resets for the account


 
Response Schema: application/json
required
Array of objects (FieldMetadata)   <= 100 items 
A page of FieldMetadata results


 
 Array (<= 100 items)
id
required
string
The field's unique identifier


 
name
required
string
The field's name


 
type
required
string
The field's type


 Enum: "enriched" "global" "list" "relationship-intelligence"  
enrichmentSource
required
string or null
The source of the data in this Field (if it is enriched)


 Enum: "affinity-data" "dealroom" "eventbrite" "mailchimp" null  
valueType
required
string
The type of the data in this Field


 Enum: "person" "person-multi" "company" "company-multi" "filterable-text" "filterable-text-multi" "number" "number-multi" "datetime" "location" "location-multi" "text" "ranked-dropdown" "dropdown" "dropdown-multi" "formula-number" "interaction"  
required
object (Pagination) 
 
prevUrl
string or null <uri> 
URL for the previous page


 
nextUrl
string or null <uri> 
URL for the next page


 
400
Bad Request


default
Errors


get/v2/persons/fields
Request samples 
Response samples 
application/json
{}
Get a single Person
Returns basic information and non-list-specific field data on the requested Person.


To retrieve field data, you must use either the fieldIds or the fieldTypes parameter
to specify the Fields for which you want data returned.
These Field IDs and Types can be found using the GET /v2/persons/fields endpoint.
When no fieldIds or fieldTypes are provided, Persons will be returned without any field data attached.
To supply multiple fieldIds or fieldTypes parameters, generate a query string that looks like this:
?fieldIds=field-1234&fieldIds=affinity-data-location or ?fieldTypes=enriched&fieldTypes=global.


Requires the "Export All People directory" permission.


SecuritybearerAuth 
Request 
path Parameters
personId
required
integer <int64>   [ 1 .. 9223372036854776000 ] 
Person ID


 
query Parameters
fieldIds
Array of strings
Field IDs for which to return field data


 
 Example:  fieldIds=field-1&fieldIds=field-2
fieldTypes
Array of strings
Field Types for which to return field data


Items Enum: "enriched" "global" "relationship-intelligence"  
 Example:  fieldTypes=enriched&fieldTypes=global
Responses 
200
OK


 Response Headers 
X-Ratelimit-Limit-User
integer
Number of requests allowed per minute for the user


 
X-Ratelimit-Limit-User-Remaining
integer
Number of requests remaining for the user


 
X-Ratelimit-Limit-User-Reset
integer
Time in seconds before the limit resets for the user


 
X-Ratelimit-Limit-Org
integer
Number of requests allowed per month for the account


 
X-Ratelimit-Limit-Org-Remaining
integer
Number of requests remaining for the account


 
X-Ratelimit-Limit-Org-Reset
integer
Time in seconds before the limit resets for the account


 
Response Schema: application/json
id
required
integer <int64>   [ 1 .. 9007199254740991 ] 
The persons's unique identifier


 
firstName
required
string
The person's first name


 
lastName
required
string or null
The person's last name


 
primaryEmailAddress
required
string or null <email> 
The person's primary email address


 
emailAddresses
required
Array of strings <email> 
All of the person's email addresses


 
type
required
string
The person's type


 Enum: "internal" "external"  
Array of objects (Field) 
The fields associated with the person


 
 Array 
id
required
string
The field's unique identifier


 
name
required
string
The field's name


 
type
required
string
The field's type


 Enum: "enriched" "global" "list" "relationship-intelligence"  
enrichmentSource
required
string or null
The source of the data in this Field (if it is enriched)


 Enum: "affinity-data" "dealroom" "eventbrite" "mailchimp" null  
required
FieldValue (object) or FieldValue (object) or FieldValue (object) or FieldValue (object) or FieldValue (object) or FieldValue (object) or FieldValue (object) or FieldValue (object) or FieldValue (object) or FieldValue (object) or FieldValue (object) or FieldValue (object) or FieldValue (object) or FieldValue (object) or FieldValue (object) or FieldValue (object) (FieldValue) 
 
400
Bad Request


403
Forbidden


404
Not Found


default
Errors


get/v2/persons/{personId}
Request samples 
Response samples 
application/json
{
  • "firstName": "Jane",
  • "lastName": "Doe",
  • "emailAddresses": [
    ],
  • "id": 1,
  • "type": "internal",
  • "fields": [
    ],
  • "primaryEmailAddress": "jane.doe@acme.co"
}
Get a Person's List Entries
Paginate through the List Entries (AKA rows) for the given Person across all Lists.
Each List Entry includes field data for the Person, including list-specific field data.
Each List Entry also includes metadata about its creation, i.e., when it was added to the List and by whom.


Requires the "Export data from Lists" permission.


SecuritybearerAuth 
Request 
path Parameters
personId
required
integer <int64>   [ 1 .. 9223372036854776000 ] 
Persons ID


 
query Parameters
cursor
string
Cursor for the next or previous page


 
 Example:  cursor=ICAgICAgYmVmb3JlOjo6Nw
limit
integer <int32>   [ 1 .. 100 ] 
 Default:  100
Number of items to include in the page


 
 Example:  limit=100
Responses 
200
OK


 Response Headers 
X-Ratelimit-Limit-User
integer
Number of requests allowed per minute for the user


 
X-Ratelimit-Limit-User-Remaining
integer
Number of requests remaining for the user


 
X-Ratelimit-Limit-User-Reset
integer
Time in seconds before the limit resets for the user


 
X-Ratelimit-Limit-Org
integer
Number of requests allowed per month for the account


 
X-Ratelimit-Limit-Org-Remaining
integer
Number of requests remaining for the account


 
X-Ratelimit-Limit-Org-Reset
integer
Time in seconds before the limit resets for the account


 
Response Schema: application/json
required
Array of objects (ListEntry)   <= 100 items 
A page of ListEntry results


 
 Array (<= 100 items)
id
required
integer <int64>   [ 1 .. 9007199254740991 ] 
The list entry's unique identifier


 
listId
required
integer <int64>   [ 1 .. 9007199254740991 ] 
The ID of the list that this list entry belongs to


 
createdAt
required
string <date-time> 
The date that the list entry was created


 
creatorId
required
integer or null <int64>   [ 1 .. 9007199254740991 ] 
The ID of the user that created this list entry


 
required
Array of objects (Field) 
The fields associated with the list entry


 
required
object (Pagination) 
 
prevUrl
string or null <uri> 
URL for the previous page


 
nextUrl
string or null <uri> 
URL for the next page


 
400
Bad Request


403
Forbidden


404
Not Found


default
Errors


get/v2/persons/{personId}/list-entries
Request samples 
Response samples 
application/json
{
  • "pagination": {},
  • "data": [
    ]
}
Get a Person's Lists
Paginate through all Lists where the given Person appears as an entry and that you have access to view.
Returns basic List information for each List that contains this Person.


SecuritybearerAuth 
Request 
path Parameters
personId
required
integer <int64>   [ 1 .. 9223372036854776000 ] 
Persons ID


 
query Parameters
cursor
string
Cursor for the next or previous page


 
 Example:  cursor=ICAgICAgYmVmb3JlOjo6Nw
limit
integer <int32>   [ 1 .. 100 ] 
 Default:  100
Number of items to include in the page


 
 Example:  limit=100
Responses 
200
OK


 Response Headers 
X-Ratelimit-Limit-User
integer
Number of requests allowed per minute for the user


 
X-Ratelimit-Limit-User-Remaining
integer
Number of requests remaining for the user


 
X-Ratelimit-Limit-User-Reset
integer
Time in seconds before the limit resets for the user


 
X-Ratelimit-Limit-Org
integer
Number of requests allowed per month for the account


 
X-Ratelimit-Limit-Org-Remaining
integer
Number of requests remaining for the account


 
X-Ratelimit-Limit-Org-Reset
integer
Time in seconds before the limit resets for the account


 
Response Schema: application/json
required
Array of objects (List)   <= 100 items 
A page of List results


 
 Array (<= 100 items)
id
required
integer <int64>   [ 1 .. 9007199254740991 ] 
The unique identifier for the list


 
name
required
string
The name of the list


 
creatorId
required
integer <int64>   [ 1 .. 9007199254740991 ] 
The ID of the user that created this list


 
ownerId
required
integer <int64>   [ 1 .. 9007199254740991 ] 
The ID of the user that owns this list


 
isPublic
required
boolean
Whether or not the list is public


 
required
object (Pagination) 
 
prevUrl
string or null <uri> 
URL for the previous page


 
nextUrl
string or null <uri> 
URL for the next page


 
400
Bad Request


404
Not Found


default
Errors


get/v2/persons/{personId}/lists
Request samples 
Response samples 
application/json
{}
Get Notes for a Person




⚠️  This endpoint is currently in BETA






Returns notes for a given person id which includes directly attached notes, notes on meetings this person attended, and notes where this person is mentioned.


You can filter notes using the filter query parameter. The filter parameter is a string that you can specify conditions based on the following properties.






Property Name
Description
Type
Allowed Operators
Examples





creator.id
Filter notes by the creator of the note
int32
=
creator.id=1




createdAt
Filter notes by when it was created
datetime
>, <, >=, <=
createdAt<2025-02-04T10:48:24Z




updatedAt
Filter notes by when it was updated
datetime
>, <, >=, <=
updatedAt>=2025-02-03T10:48:24Z





SecuritybearerAuth 
Request 
path Parameters
personId
required
integer <int64>   [ 1 .. 9223372036854776000 ] 
Persons ID


 
query Parameters
filter
string
Filter options


 
cursor
string
Cursor for the next or previous page


 
limit
integer <int32>   [ 0 .. 100 ] 
 Default:  20
Number of items to include in the page


 
totalCount
boolean
 Default:  false
Include total count of the collection in the pagination response


 
Responses 
200
OK


 Response Headers 
X-Ratelimit-Limit-User
integer
Number of requests allowed per minute for the user


 
X-Ratelimit-Limit-User-Remaining
integer
Number of requests remaining for the user


 
X-Ratelimit-Limit-User-Reset
integer
Time in seconds before the limit resets for the user


 
X-Ratelimit-Limit-Org
integer
Number of requests allowed per month for the account


 
X-Ratelimit-Limit-Org-Remaining
integer
Number of requests remaining for the account


 
X-Ratelimit-Limit-Org-Reset
integer
Time in seconds before the limit resets for the account


 
Response Schema: application/json
required
Array of any (notes.Note)   <= 100 items 
A page of Note objects


 
 Array (<= 100 items)
type
required
string
The type of the note


 
 Value:  "entities"
repliesCount
integer <int32>   [ 0 .. 2147483647 ] 
The number of replies to this note. This is only included if the repliesCount parameter is passed in the includes in the request and the note is not a reply itself.


 
object (notes.PermissionSettings) 
The permission settings of a note


 
object (notes.OpportunitiesPreview) 
A preview for attached Opportunities on a Note


 
object (notes.PersonsPreview) 
A preview for attached Persons on a Note


 
object (notes.CompaniesPreview) 
A preview for attached Companies on a Note


 
id
required
integer <int32>   [ 1 .. 2147483647 ] 
The id of the note


 
required
object (notes.Content) 
A note content


 
required
object (PersonData) 
 
required
Array of any (notes.Mention)   <= 100 items 
The mentions in the note


 
createdAt
required
string <date-time> 
The date and time the note was created


 
updatedAt
required
string or null <date-time> 
The date and time the note was last updated


 
required
object (PaginationWithTotalCount) 
 
totalCount
integer <int64>   [ 0 .. 9007199254740991 ] 
The total count of the collection. Only included if requested via the totalCount query string parameter.


 
prevUrl
string or null <uri> 
URL for the previous page


 
nextUrl
string or null <uri> 
URL for the next page


 
400
Bad Request


404
Not Found


default
Errors


get/v2/persons/{personId}/notes
Request samples 
Response samples 
application/json
{
  • "data": [
    ],
  • "pagination": {}
}
➔ Next to transcripts