Skip to main content
The contacts endpoint returns contacts one page at a time. Each response includes a cursor that marks where the page ended. Send it back in your next request to get the following page, and stop when the API tells you there are no more. GET /public/v2/workspaces/{workspaceID}/contacts
Offset pagination (limit with offset) will be deprecated soon. See Coming from offset pagination?.

Prerequisites

Prepare these values before you start:
  • WORKSPACE_ID
  • SALESFORGE_API_KEY
Send the raw API key in the Authorization header:
For the shared authentication pattern, see Authentication.

How it works

1

Request the first page

Add pagination=cursor to your request. Use limit to set the page size. The default is 10 and the maximum is 1000.
A request with no pagination and no cursor still uses offset pagination, which will be deprecated soon. See Coming from offset pagination?.
2

Read the response

The response has the contacts for this page and the information you need to get the next one:
  • data is the list of contacts on this page.
  • limit is the page size the API used.
  • hasMore is true when more contacts are available.
  • nextCursor is the value to send in your next request. It is missing on the last page.
3

Request the next page

Send nextCursor as the cursor parameter. You don’t need to send pagination=cursor again. Keep the same workspace, limit, and filters.
4

Stop when hasMore is false

Repeat the previous step until hasMore is false. Check hasMore to decide when to stop. Don’t count pages, and don’t stop because a page has fewer contacts than limit.

Code examples

Each example reads every contact in a workspace, one page at a time.

Filter contacts

You can filter the list. Send the same filters on every page of the same listing. For example, to read all contacts with one tag:
The API returns a 400 error for query parameters it doesn’t know. Check the spelling of each filter.

Rules to remember

  • A cursor is an opaque string. Don’t build it, edit it, or store it for a long time. Use the nextCursor from the last response.
  • A cursor works only for the workspace that created it. If you use it with another workspace, the API returns a 400 error.
  • Keep the same filters and limit on every request in the same listing.
  • Contacts come back in a fixed order, so you don’t get the same contact twice while you page.
  • A response doesn’t include a total number of contacts. To get the total, call GET /public/v2/workspaces/{workspaceID}/contacts/count with the same filters.
  • Listing contacts is rate limited per account: 60 requests per minute, a burst of 10, and 2 requests in flight. Read the pages one after another, and when you get 429, wait for Retry-After before you send the request again. See Rate limits.

Coming from offset pagination?

Offset pagination will be deprecated soon. Requests that use offset, or that send neither pagination nor cursor, still work today. Move to cursor pagination before the deprecation.
Offset pagination reads a page by skipping a number of contacts, as in limit=100&offset=5000. Cursor pagination replaces the offset with a cursor that marks where the last page ended. Offset requests also get slower as the offset grows. To migrate, make these changes in your code:
1

Choose cursor mode on the first request

Send pagination=cursor and remove offset.
2

Replace the offset with a cursor

Don’t increase offset by limit after each page. Send the nextCursor from the last response as cursor.
3

Change how your loop stops

Stop when hasMore is false. Don’t stop by comparing offset with total, and don’t stop when a page is smaller than limit.
4

Replace total with the count endpoint

Cursor responses have no total and no offset. If you show a total or a progress bar, call GET /public/v2/workspaces/{workspaceID}/contacts/count once, with the same filters.
Here is how the response changes:
You can’t use offset together with cursor or pagination=cursor. The API returns a 400 error.

Errors