Pagination

List endpoints use cursor-based pagination to efficiently page through large result sets.

How It Works

Make your first request with an optional limit
If there are more results, the response includes a next_cursor
Pass next_cursor as cursor in your next request
Repeat until next_cursor is empty or absent

Example

First page:

curl -X POST https://api.driftwoodapp.com/api/contacts-list \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"limit": 25}'

{
  "ok": true,
  "result": {
    "items": [ ... 25 contacts ... ],
    "next_cursor": "MjAyNS0wNi0wMVQxMjowMDowMFp8NTUwZTg0MDA..."
  }
}

Next page:

curl -X POST https://api.driftwoodapp.com/api/contacts-list \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 25,
    "cursor": "MjAyNS0wNi0wMVQxMjowMDowMFp8NTUwZTg0MDA..."
  }'

Last page (no more results):

{
  "ok": true,
  "result": {
    "items": [ ... 12 contacts ... ],
    "next_cursor": ""
  }
}

Parameters

Parameter	Type	Default	Description
`cursor`	string	–	Pagination cursor from a previous response
`limit`	integer	25	Number of items per page (max varies by endpoint)

Ordering

Results are ordered by created_at descending (newest first). The cursor encodes both the timestamp and record ID to ensure stable pagination even when new records are created between pages.

Iterating All Records

def get_all_contacts(token):
    contacts = []
    cursor = None
    while True:
        body = {"limit": 100}
        if cursor:
            body["cursor"] = cursor
        result = driftwood_api("contacts-list", token, body)
        contacts.extend(result["items"])
        cursor = result.get("next_cursor")
        if not cursor:
            break
    return contacts

Endpoints Using Cursor Pagination

contacts-list
companies-list
projects-list
activities-list
inbound-emails-list
imports-errors