Lists

List a list's rows

One page of a list’s rows: people in a people list, companies in a company list, as type says. A row’s columnValues holds the values of the list’s own columns, by column id.

For the next page, send the page’s pagination.nextCursor as cursor. Later pages keep the first page’s pageSize; only a missing nextCursor marks the end. Send the same filters and sort with it.

filters narrows the rows: a JSON object in which a row must match every key, and any of a key’s values. Text keys take an array of values or {"include": [...], "exclude": [...]}: name, title, dept, level, industryName, country, state, personalLocation, companyName, companyIndustry, companyHeadQuartersCountry, companyLocation, website, campaignEngagement and otherLists (the names of other lists). numberOfEmployees takes ranges written as strings, such as "51-200" or "10001+", and revenue a number. keywords (a job title, with * and ? as wildcards) and linkedinUrl take one string.

enrichedEmail (enriched, not_enriched, no_emails_found), enrichedPhone (enriched, not_enriched) and emailValidity (valid, invalid, catch-all, unknown, do_not_mail, personal, unverified) take {"include": [...]} or {"exclude": [...]}. 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 take companyName, companyIndustry, companyHeadQuartersCountry, website, numberOfEmployees, campaignEngagement and customColumns.

Values for level, dept, industryName and country are the people search’s own, from GET /v1/people/filters, and website is a bare domain. A key the list kind does not take, or a value of the wrong shape, answers 422 invalid_row_filters; a value no row has matches nothing.

Free. Scope: lists. Read-only keys may call it.

GET

lists

{listId}

rows

List a list's rows

curl --request GET \
  --url https://api.outbound.dev/v1/lists/{listId}/rows \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.outbound.dev/v1/lists/{listId}/rows', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "type": "people",
  "data": [
    {
      "id": "6a1f0c2b9d4e8a7f3c5b2e22",
      "firstName": "Ana",
      "lastName": "Costa",
      "linkedinUrl": "https://www.linkedin.com/in/ana-costa",
      "jobTitle": "Head of Operations",
      "companyName": "Northwind Freight",
      "companyDomain": "northwind.example",
      "emails": [
        {
          "email": "ana.costa@example.com",
          "status": "valid",
          "isPersonal": false
        }
      ],
      "phones": [],
      "primaryEmail": "ana.costa@example.com",
      "lists": [
        {
          "id": "6a1f0c2b9d4e8a7f3c5b2e20",
          "name": "Portugal freight ops"
        }
      ],
      "source": "csv_upload",
      "location": {
        "city": "lisbon",
        "country": "portugal"
      },
      "columnValues": {
        "6a1f0c2b9d4e8a7f3c5b2e24": "Runs a 40-truck fleet"
      }
    }
  ],
  "pagination": {
    "pageSize": 100,
    "nextCursor": "MjoxMDA",
    "total": 242
  }
}

{
  "error": {
    "code": "insufficient_balance",
    "message": "Your balance cannot cover this call. Add funds and try again.",
    "doc_url": "https://docs.outbound.dev/errors#insufficient_balance",
    "request_id": "req_6a1f0c2b9d4e8a7f3c5b2e10"
  }
}

Authorizations

Authorization

string

header

required

An API key from the console, starting ob_live_, sent as Authorization: Bearer <key>.

Path Parameters

listId

string

required

The list's id.

Required string length: 24

Pattern: ^[0-9a-fA-F]+$

Query Parameters

pageSize

integer

default:100

Rows per page.

Required range: 1 <= x <= 1000

cursor

string

The pagination.nextCursor of the page before. Later pages keep the first page's size.

Required string length: 1 - 200

sortBy

string

The field to sort by. People lists: firstName, lastName, jobTitle, createdAt, address.city, address.country, a company field such as company.name or company.linkedInHeadCount, or customColumns_<columnId>. Company lists: name, domain, industry, revenue, linkedInHeadCount or customColumns_<columnId>. A field it does not know keeps the list's own order.

Required string length: 1 - 100

sortOrder

enum<string>

default:asc

The order sortBy sorts in.

Available options:

asc,

desc

filters

string

Only the rows that match: a JSON object of row filters, at most 8,000 characters, in the keys this route describes.

Maximum string length: 8000

Response

One page of the list's rows.

type

enum<string>

required

What the rows are: people or company.

Available options:

people,

company

data

object[]

required

Show child attributes

pagination

object

required

Show child attributes

List a list's rows

curl --request GET \
  --url https://api.outbound.dev/v1/lists/{listId}/rows \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.outbound.dev/v1/lists/{listId}/rows', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "type": "people",
  "data": [
    {
      "id": "6a1f0c2b9d4e8a7f3c5b2e22",
      "firstName": "Ana",
      "lastName": "Costa",
      "linkedinUrl": "https://www.linkedin.com/in/ana-costa",
      "jobTitle": "Head of Operations",
      "companyName": "Northwind Freight",
      "companyDomain": "northwind.example",
      "emails": [
        {
          "email": "ana.costa@example.com",
          "status": "valid",
          "isPersonal": false
        }
      ],
      "phones": [],
      "primaryEmail": "ana.costa@example.com",
      "lists": [
        {
          "id": "6a1f0c2b9d4e8a7f3c5b2e20",
          "name": "Portugal freight ops"
        }
      ],
      "source": "csv_upload",
      "location": {
        "city": "lisbon",
        "country": "portugal"
      },
      "columnValues": {
        "6a1f0c2b9d4e8a7f3c5b2e24": "Runs a 40-truck fleet"
      }
    }
  ],
  "pagination": {
    "pageSize": 100,
    "nextCursor": "MjoxMDA",
    "total": 242
  }
}

{
  "error": {
    "code": "insufficient_balance",
    "message": "Your balance cannot cover this call. Add funds and try again.",
    "doc_url": "https://docs.outbound.dev/errors#insufficient_balance",
    "request_id": "req_6a1f0c2b9d4e8a7f3c5b2e10"
  }
}

People

Companies

Saved searches

Lists

Folders

Jobs

Account

Billing

Usage and requests

List a list's rows

Authorizations

Path Parameters

Query Parameters

Response