If your list returns a large number of rows you can generate a snapshot of the results and retrieve the data from the snapshot - this has the benefit over the simpler list results retrieval method as the results are guaranteed not to change as they are paged and ordering & retrieval after generation will be quicker. 

A snapshot of list can be generated by calling the async results endpoint https://data.donorfy.com/api/v1/<apikey>/lists/<listId>/asyncresults/ 

This will queue the generation of a new snapshot and return a json object which will include a continuation token. By sending the continuation token in future requests - see example below - it is possible to poll for completion of the snapshot and retrieve the data when it is ready.

This is an example sequence against a list id E4F3B6CF-D468-42D2-9C8A-117633BA9B62 - you would make a call to the asyncresults endpoint shown below including the list id 

https://data.donorfy.com/api/v1/<apikey>/lists/E4F3B6CF-D468-42D2-9C8A-117633BA9B62/asyncresults/ fromRow=0&numberOfRows=1000

The call above would start the snapshot generation and return a continuation token - e.g. 7DFBB5AD-3764-4945-8288-55DF18985196 - the call would also return the http status code 202 as the snapshot is still being generated.

The status code 202 will continue to be returned by the endpoint until the generation is complete then 200 would be returned, you would make a request to the URL including the continuation token e.g. once a minute and check the status code returned waiting for a 200

https://data.donorfy.com/api/v1/<apikey>/lists/E4F3B6CF-D468-42D2-9C8A-117633BA9B62/asyncresults/7DFBB5AD-3764-4945-8288-55DF18985196 fromRow=0&numberOfRows=1000

Once the 200 status code is returned you would retrieve the data in pages by incrementing the fromRow including the continuation token e.g. 

• https://data.donorfy.com/api/v1/<apikey>/lists/E4F3B6CF-D468-42D2-9C8A-117633BA9B62/asyncresults/7DFBB5AD-3764-4945-8288-55DF18985196 fromRow=1000&numberOfRows=1000
• https://data.donorfy.com/api/v1/<apikey>/lists/E4F3B6CF-D468-42D2-9C8A-117633BA9B62/asyncresults/7DFBB5AD-3764-4945-8288-55DF18985196 fromRow=2000&numberOfRows=1000
• https://data.donorfy.com/api/v1/<apikey>/lists/E4F3B6CF-D468-42D2-9C8A-117633BA9B62/asyncresults/7DFBB5AD-3764-4945-8288-55DF18985196 fromRow=3000&numberOfRows=1000

Note the following  

• You should include a continuation token in the request, if it is not included then a new snapshot will be queued for generation. 
• You can expect a 202 status code to be returned by a request whilst the snapshot is being generated
• A snapshot will be removed after 4 hours and the continuation token will return a status code of 404 - a not found result will also be returned if an invalid continuation token is used
• Sort the results by including the sortBy parameter e.g. https://data.donorfy.com/api/v1/<apikey>/lists/<listId>/asyncresults?sortBy=DateAdded if you do not specify a sort order the results will be returned in EntityNumber order, you can sort by any fields in the results returned
• Retrieve the list results in batches (or pages) by appending the parameters fromRow and numberOfRows to the request - e.g. https://data.donorfy.com/api/v1/<apikey>/lists/<listId>/ asyncresults?fromRow=100&numberOfRows=50  note that
  • The first row is row zero, so pass fromRow=0 to retrieve the results starting from the first row in the results, if fromRow is not passed then zero will be used
  • Use numberOfRows to indicate how many rows you want in the batch if
    • you do not pass a value for numberOfRows then the next 100 rows will be returned
    • the maximum value for numberOfRows is 1000 if you request more than 1000 rows only 1000 rows will be returned
  • Batching respects the sort order - i.e. changing the sort order will affect which rows are included in a given batch of results 
  • If the combination of fromRow and numberOfRows requests more rows than exist in the list results - i.e. you are requesting more results than the list has, or requesting rows past the end of the results - then fewer results than the number of rows requested (or zero results) will be returned

The results will be returned as a list of result row presented as JSON objects - at the start of the row data there will be the following fields

• EntityId - this is the Id of the entity - e.g. if you are using a constituent list this would be the constituent id
• Entity - the type of entity - e.g. Constituent, Transaction, Activity and so on
• EntityNumber - the number allocated to the entity

You can use these values to make further API calls.

The remaining fields in the row data will change depending on the type of list.

The Donorfy API is a Professional-only feature. Essential subscribers, please contact us to find out more about upgrading.