v1

latestOpenAPI 3.1.02026-07-26359254.7 MB

Contacts

Filter contacts

<small>Requires the contacts:read scope (or a broader one that includes it).</small>

Use this endpoint when you need a filtered, sorted page of contacts that a plain email or LinkedIn lookup cannot express. Combine field rules (property, condition, value) with optional scoping by list, sequence, or sequence step, a free-text search term, and a sort order. Results are paged with the top and skip query parameters. To get only the total for the same criteria, use filter/count.

post/v3/contacts/filter

Query parameters

topinteger

Maximum number of contacts to return (default 25, max 1000)

skipinteger

Number of contacts to skip

Request body

listIdinteger nullable

Filter by contact list ID

sequenceIdinteger nullable

Filter by sequence ID

sequenceStepIdinteger nullable

Filter by sequence step ID

searchTermstring nullable

Free-text search term

sortBystring nullable

Field to sort by

sortDirectionstring nullable

Sort direction (asc or desc)

Response

Filtered contacts retrieved successfully

hasMoreboolean

Indicates if there are more items to fetch

Example response

{
  "items": [
    {
      "id": 12345,
      "email": "john.doe@company.com",
      "firstName": "John",
      "lastName": "Doe",
      "title": "Senior Product Manager",
      "company": "Tech Solutions Inc",
      "domain": "company.com",
      "companySize": "oneThousand",
      "city": "San Francisco",
      "state": "CA",
      "country": "United States",
      "timeZoneId": "America/Los_Angeles",
      "phone": "+1-415-555-0123",
      "phoneStatus": "valid",
      "linkedInUrl": "https://www.linkedin.com/in/johndoe",
      "linkedInSalesNavigatorUrl": "https://www.linkedin.com/sales/profile/123456",
      "linkedInRecruiterUrl": "https://www.linkedin.com/recruiter/profile/789012",
      "industry": "Software & Technology",
      "notes": "Met at SaaS Conference 2024",
      "ownerUserId": 42,
      "accountId": 100,
      "isOptedOut": false,
      "callStatus": "toCall",
      "meetingStatus": "none",
      "addingDate": "2024-03-08T10:00:00+00:00",
      "createdAt": "2024-03-08T10:00:00",
      "lastModifiedAt": "2024-03-10T15:30:00",
      "customFields": [
        {
          "key": "leadSource",
          "value": "Conference"
        },
        {
          "key": "budget",
          "value": "100k-250k"
        }
      ]
    }
  ]
}