This article provides information about using Lists via the API. Lists are built using the Donorfy UI and return a list of items that match any filter applied to the list.

The API allows you to retrieve

• The lists that exist in your Donorfy - for example, if you are writing an integration you could allow people to choose the list to provide data to your integration
• The results - i.e. rows returned - by a list

You can retrieve the all the lists via a get request to the https://data.donorfy.com/api/v1/<apikey>/lists/  for each list this will return 

• The list ID
• List description
• List Type
• The row count for the list when it was last run, together with the date of the row count - when the list results are retrieved - see details below - the row count will be updated. 

You can retrieve the all the lists of a given type by adding a listType parameter to the request - e.g. https://data.donorfy.com/api/v1/<apikey>/lists?listType=Constituent  

Details of an individual list can be retrieved by a call to https://data.donorfy.com/api/v1/<apikey>/lists/<listId>/ - the list ID indicates which list you want the results for.

The list ID can be determined by either:

• a call to https://data.donorfy.com/api/v1/<apikey>/lists/ endpoint and then selecting the list you want from the lists returned 
• open the list in the Donorfy UI and copy the list Id from URL - as shown in the example below

Retrieving the List Results 

The results of a list can be retrieved by a get request to https://data.donorfy.com/api/v1/<apikey>/lists/<listId>/results/ 

The results of a list are dynamic - i.e. changes made to the list definition or to the data in Donorfy will immediately affect the results returned by the API calls.

Note if your list returns a large number of results you can use the async results end point which has better performance for large result sets - see this article for more information

You 

• Can sort the results by including the sortBy parameter e.g. https://data.donorfy.com/api/v1/<apikey>/lists/<listId>/results?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
• Should retrieve the list results in batches (or pages) this is done by appending the parameters fromRow and numberOfRows to the request - e.g. https://data.donorfy.com/api/v1/<apikey>/lists/<listId>/results?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 that 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.