Search List Entries

⚠️ This endpoint is currently in BETA

Search for List Entries on a List matching the given criteria.

Accepts an optional combination of filters, sorts, and a search term. All fields in the request body are optional. Omitting the body entirely is equivalent to GET /v2/lists/{listId}/list-entries with default pagination.

Requires the "Export data from Lists" permission.

Field IDs

Field IDs used in filters, sorts, and search.fieldIds follow the formats described in Working with Field Data. Use GET /v2/lists/{listId}/fields?includes=filterability to discover which fields are filterable and what operators each supports. Use GET /v2/lists/{listId}/fields?includes=sortability for sortable fields.

attributeId

Some fields require an attributeId to specify which aspect to filter or sort on. The following relationship intelligence fields all use attributeId: "date-of-activity": last-email, first-email, last-contact, last-event, first-event, next-event.

Use GET /v2/lists/{listId}/fields?includes=filterability to confirm which fields require an attributeId.

Search

The search.term is always matched against the entity's name and primary identifier: company name and primary domain (company lists), person first name, last name, and primary email address (person lists), or opportunity name (opportunity lists). Providing search.fieldIds extends the search to those additional fields; it does not restrict matching to only those fields. Fields with a valueType of datetime are not searchable and are silently ignored if included in search.fieldIds.

Limits

Items per filter group (filters or nested groups): 50
Values per filter (e.g. options in is-any-of): 100
Sort criteria: 5
Search term minimum length: 3 characters
Results per page: 100

Pagination

Uses cursor-based pagination.

listIdinteger required

The ID of the List to search

fieldIdsstring[]

Specific field IDs for which to return field data on each List Entry. Cannot be used together with fieldTypes — use one or the other. Use GET /v2/lists/{listId}/fields to discover available field IDs.

fieldTypesstring[]

A category of fields for which to return field data on each List Entry. Cannot be used together with fieldIds — use one or the other.

cursorstring

Cursor for the next or previous page.

limitinteger

Maximum number of List Entries to return per page

totalCountboolean

When true, includes the total count of matching List Entries in the pagination response. Adds additional query cost; use only when needed.

Request body

Example request

{
  "filters": {
    "filters": [
      {
        "value": [
          {
            "id": 1
          }
        ]
      }
    ]
  }
}

Response

Created

Example response

{
  "data": [
    {
      "id": 1,
      "type": "company",
      "listId": 1,
      "createdAt": "2023-01-01T00:00:00Z",
      "creatorId": 1,
      "entity": {
        "id": 1,
        "name": "Horizon Technologies",
        "domain": "horizontech.com",
        "domains": [
          "horizontech.com"
        ],
        "isGlobal": true,
        "fields": []
      }
    }
  ],
  "pagination": {
    "prevUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgYmVmb3JlOjo6Nw",
    "nextUrl": "https://api.affinity.co/v2/foo?cursor=ICAgICAgIGFmdGVyOjo6NA"
  }
}

v1