This method is recommended when lists return a large number of rows or when consistent ordering across pages is required.
Understand Why to Use Asynchronous List Results
Asynchronous list retrieval creates a snapshot of the list at a specific point in time.
Prevent list results from changing while paging through data.
Improve performance compared to retrieving live list results page by page.
The snapshot remains available for a limited time and can be queried repeatedly using a continuation token.
Generate a List Snapshot
Start by requesting the asynchronous results endpoint for your list.
Make a request to the async results endpoint for the list:
https://data.donorfy.com/api/v1/<apikey>/lists/<listId>/asyncresults/Include paging parameters if required.
Example pattern:
Endpoint:
/lists/{listId}/asyncresults/
This queues snapshot generation and returns a continuation token.
The initial request typically returns HTTP status 202, indicating the snapshot is still being generated.
Poll for Snapshot Completion
You must poll the endpoint until snapshot generation completes.
Re-send the request using the returned continuation token.
Check the HTTP status code.
Status codes:
202: Snapshot is still being generated.
200: Snapshot is ready and results can be retrieved.
Polling once per minute is usually sufficient.
Retrieve Results in Batches
Once the snapshot is ready, retrieve results in pages.
Include the continuation token in the request URL.
Use fromRow and numberOfRows to control paging:
https://data.donorfy.com/api/v1/<apikey>/lists/<listId>/ asyncresults?fromRow=100&numberOfRows=50
Paging rules:
The first row index is 0.
Default batch size is 100 rows.
Maximum numberOfRows value is 1000.
If you request beyond the end of the list, fewer or zero rows are returned.
If you omit the continuation token, a new snapshot will be generated instead of using the existing one.
Understand Snapshot Lifetime
Snapshots are temporary.
📌 Note: Snapshots expire after 4 hours.
After expiry, requests return 404 Not Found.
Invalid continuation tokens also return 404.
If a snapshot expires, you must generate a new one.
Sort Snapshot Results
You can control the sort order of results.
You can sort the results by including the sortBy parameter e.g. https://data.donorfy.com/api/v1/<apikey>/lists/<listId>/asyncresults?sortBy=DateAdded
Use any valid column name from the list.
Sorting behaviour:
If sortBy is not specified, results are sorted by EntityNumber.
If an invalid column name is supplied, a 500 error is returned.
Sorting affects paging results.
Changing the sort order changes which rows appear in each batch.
Understand the Result Structure
Each row in the response includes common identifier fields.
Returned fields include:
EntityId: The unique ID of the entity.
Entity: The entity type, such as Constituent or Transaction.
EntityNumber: The entity’s reference number.
Additional fields depend on the list type and its selected columns.
You can use the returned identifiers to make further API calls for detailed data.
⚠️Important:
The Donorfy API is a Professional only feature. Essential subscribers, please contact us to find out more about upgrading.