Skip to main content
Lists hold the people you work with, and folders keep the lists in order. Every list and folder call is free.

Create a list

A list holds people unless you send "type": "company", and its kind cannot change later. No two lists of an organization share a name: a name in use answers 409 with list_name_taken.

Add your own rows

POST /v1/lists/{listId}/rows adds up to 500 people from what you know about them. Each row needs at least one of email, linkedinUrl, firstName and lastName:
  • Nothing is looked up. An email address is kept as sent, unchecked.
  • Every row becomes a new person, even one already in your workspace. Sending the same call twice adds everyone twice.
  • Only people lists take rows. A company list answers 422 with people_list_required.

Add people already in your workspace

To put the same people in another list, send their ids: the personIds an upload answered with, or the id of their row in another list. Up to 5,000 a call:
People already in the list are skipped, so sending the call again adds nobody twice. DELETE /v1/lists/{listId}/people with the same body takes people out of a list: they stay in your workspace and in their other lists.

Read a list’s rows

GET /v1/lists/{listId}/rows answers one page of rows, up to 1,000 at a time, in the order sortBy and sortOrder ask for:
Each row carries the person’s name, title, company, emails and phones, the lists they are in, and columnValues: the values of the list’s own columns, by column id. For the next page, send pagination.nextCursor as cursor with the same sort and filters. See Pagination.

Filter the rows

filters is a JSON object in which a row must match every key, and any of a key’s values. Text keys such as title, companyName or country take an array of values, or include and exclude arrays:
Values for level, dept, industryName and country are the people search’s own, from GET /v1/people/filters. A key the list’s kind does not take, or a value of the wrong shape, answers 422 with invalid_row_filters. Every key is in List a list’s rows.

Keep lists in folders

Move a list into it by the folder’s id, or by its name with folderName, which creates the folder when there is none:
  • A folder holds one kind of list. A people list goes only into a folder for people lists: any other folder answers 404 with folder_not_found.
  • "folderId": null takes a list out of every folder.
  • GET /v1/lists?folderId=... answers the lists in one folder, and GET /v1/folders every folder for one kind of list.
  • Deleting a folder keeps its lists, out of every folder.

Delete a list

DELETE /v1/lists/{listId} deletes a list and its own columns. Its people stay in your workspace and in every other list they are in.

Keys and limits

Reading lists, rows and folders works with any key that has the lists scope, read-only keys included. Creating, changing and deleting them needs a key that can write. Every list and folder call shares one rate limit: 120 calls a minute and 10,000 a day.