---
title: "List a list's contacts (with ids and column values)"
method: GET
path: "/business/lists/{listId}/rows"
tags: ["Lists"]
---

# List a list's contacts (with ids and column values)

`GET /business/lists/{listId}/rows`

## Request

- Base URL: `https://api.tryfuse.ai/api/v1`
- URL: `https://api.tryfuse.ai/api/v1/business/lists/{listId}/rows`
- Auth: HTTP basic

Pages through a list's rows. `entityType` says which shape `data` holds: a contact list's rows carry the contact id (the id `members`, `columns/{columnId}/values`, `enrich` and `crm-push` accept), the discovered emails and phones with their validation status, the primaries, ICP match, campaign engagement, acquisition source, the other lists the contact belongs to, its location and `columnValues` (custom and smart column cells keyed by column id); a company list's rows carry the company's own fields (name, domain, industry, employeeCount, revenue, headquartersCountry) plus engagement, source, location and `columnValues`. LinkedIn URLs come back as full https URLs. `sortBy`/`sortOrder` sort (an unrecognised sort key falls back to the list's default order). `filters` is a URL-encoded JSON object in the row-filter language: text keys take an array of accepted values or `{include, exclude}` — `{"companyName":["pomelo"]}`, `{"country":["argentina"]}`; `enrichedEmail`/`enrichedPhone`/`emailValidity` take `{"include":[...]}` of their statuses; `icpMatch` takes `["yes"]` or `["no"]`; `customColumns` maps a column id to `{"dataType":"string","include":[...]}`. Two keys are narrower than their names suggest: `keywords` is a wildcard match on the job title alone (`*` and `?` are the only wildcards; other regex characters are rejected) and `otherLists` matches other lists by NAME, not by id. An unknown key or a wrong value shape answers 422 INVALID_ROW_FILTERS naming the offending key.

Errors:
- `404` `LIST_NOT_FOUND` — No list with that id is visible to the token owner.
- `422` `INVALID_ROW_FILTERS` — filters is not a JSON object, carries an unknown key, a value has the wrong shape, or `keywords` carries one of the regex metacharacters . ^ $ + ( ) [ ] { } | \ (the offending key is named in the message).
- `422` `VALIDATION_FAILED` — limit/pageNum/sortOrder out of range, or filters longer than 8000 characters.
- `429` `RATE_LIMITED` — The lists rate bucket (120 requests/minute, 10,000/day per token owner) is exhausted.

Requires one of the following token scopes: lists.

## Path parameters

- `listId` string, required: 24-character hex id of the list (from GET /business/lists).

## Query parameters

- `limit` integer: Page size: how many rows to return per page (1-1000, default 100).
- `pageNum` integer: 1-based page number (default 1).
- `sortBy` string: Field to sort rows by; it is IGNORED unless sortOrder is sent with it. Contact lists: any field on the contact record — the index-backed and therefore fast ones are firstName, lastName, jobTitle, createdAt, address.city and address.country (updatedAt carries NO index on the contact collection, so it is accepted but sorts as a blocking in-memory sort); a company field prefixed with company., where the accepted values are exactly company.name, company.domain, company.industry, company.country, company.type, company.revenue, company.linkedInHeadCount, company.address.city, company.address.state and company.address.country; or customColumns_<columnId> for a custom/smart column. Company lists: a company field by its own name (name, domain, industry, revenue, linkedInHeadCount) or customColumns_<columnId>. An unrecognised key is accepted and falls back to the list's default order rather than erroring.
- `sortOrder` 'asc' | 'desc': Sort direction: asc (ascending) or desc (descending). Required for sortBy to take effect — without it the rows keep their default order.
- `filters` string: URL-encoded JSON object (max 8000 characters) narrowing which rows are returned, e.g. {"companyName":["pomelo"]} or {"country":["argentina"]}. Text keys (name, title, dept, level, industryName, country, state, personalLocation, companyName, companyIndustry, companyHeadQuartersCountry, companyLocation, website, campaignEngagement, otherLists) take an array of accepted values, e.g. {"companyName":["pomelo"]} or {"country":["argentina"]}, or {"include":[...],"exclude":[...]} — otherLists takes list NAMES, not ids; numberOfEmployees takes headcount ranges the same way but as STRINGS ("51-200", "10001+" or a bare head count "500" — an unquoted JSON number answers 500) and revenue a plain number; keywords (a wildcard match on the job title only) and linkedinUrl take one string; enrichedEmail, enrichedPhone and emailValidity take {"include":[...]} of their statuses; icpMatch takes ["yes"] or ["no"]; customColumns maps a column id to {"dataType":"string","include":[...]}, {"dataType":"boolean","value":true} or {"dataType":"number","rangeMin":1,"rangeMax":10}. Company lists honour companyName, companyIndustry, companyHeadQuartersCountry, website, numberOfEmployees, campaignEngagement and customColumns. Every key is optional; an unknown key or a wrong value shape is rejected rather than ignored. Values inside one key are OR-joined and different keys are AND-ed. VALUES ARE NOT VALIDATED: level, industryName, country, state, website and companyHeadQuartersCountry are matched as whole values and campaignEngagement, icpMatch and enum cells as exact strings, so a value in the wrong vocabulary is accepted and silently matches nothing — each key's own description names its vocabulary and the endpoint that serves it. Malformed JSON, an unknown key or a wrong value shape answers 422 INVALID_ROW_FILTERS.

## Response `200`

Success

- object
  - `entityType` 'contactList' | 'companyList', required
  - `data` object[], required: Contact rows when entityType is contactList, company rows when it is companyList.
    - `id` string
    - `firstName` string, nullable: Contact rows only.
    - `lastName` string, nullable: Contact rows only.
    - `linkedinUrl` string, nullable: Contact rows only; a full https URL.
    - `jobTitle` string, nullable: Contact rows only.
    - `companyName` string, nullable: Contact rows only.
    - `companyDomain` string, nullable: Contact rows only.
    - `emails` object[]: Contact rows only.
      - `email` string, required
      - `status` 'valid' | 'invalid' | 'catch-all' | 'unknown' | 'do_not_mail' | 'unverified' | 'null', nullable, required
      - `isPersonal` boolean, required
    - `phones` object[]: Contact rows only.
      - `phoneNumber` string, required
      - `status` 'valid' | 'hq' | 'unverified' | 'null', nullable, required
    - `primaryEmail` string, nullable: Contact rows only.
    - `primaryPhone` string, nullable: Contact rows only.
    - `icpMatch` boolean, nullable: Contact rows only.
    - `name` string, nullable: Company rows only.
    - `domain` string, nullable: Company rows only.
    - `industry` string, nullable: Company rows only.
    - `employeeCount` integer, nullable: Company rows only.
    - `revenue` string, nullable: Company rows only.
    - `headquartersCountry` string, nullable: Company rows only; free text, not a single vocabulary — either an ISO-3166 alpha-3 code ("NLD") or a full lower-case country name ("united states"), depending on which enrichment path wrote it.
    - `engagement` string, nullable
    - `source` string, nullable
    - `lists` object[]: Contact rows only.
      - `id` string
      - `name` string
    - `location` object, nullable
      - `city` string, nullable
      - `state` string, nullable
      - `country` string, nullable
    - `columnValues` object
  - `pagination` object, required
    - `pageNum` integer, required
    - `totalPages` integer
    - `totalRecords` integer

## Other responses

- `400`: Error
- `401`: Error
- `402`: Error
- `403`: Error
- `404`: Error
- `409`: Error
- `422`: Error
- `429`: Error
- `500`: Error

---

[API](https://skmtc.dev/fuseai/apis/fuse-business-api.md) · [All operations](https://skmtc.dev/fuseai/apis/fuse-business-api/llms.txt) · [OpenAPI document](https://skmtc.dev/fuseai/apis/fuse-business-api/revisions/50d95e0536f4?raw)