GET /public/v2/workspaces/{workspaceID}/contacts
Prerequisites
Prepare these values before you start:WORKSPACE_IDSALESFORGE_API_KEY
Authorization header:
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.2
Read the response
The response has the contacts for this page and the information you need to get the next one:
datais the list of contacts on this page.limitis the page size the API used.hasMoreistruewhen more contacts are available.nextCursoris 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
nextCursorfrom the last response. - A cursor works only for the workspace that created it. If you use it with another workspace, the API returns a
400error. - Keep the same filters and
limiton 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/countwith 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 forRetry-Afterbefore you send the request again. See Rate limits.
Coming from offset pagination?
Offset pagination reads a page by skipping a number of contacts, as inlimit=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.