Skip to main content

Use Lists via the API

Access lists created in Donorfy and retrieve their results programmatically using the API

Cristina Gruita avatar
Written by Cristina Gruita
Updated over a month ago

Understand How Lists Work

Lists in Donorfy are built in the UI using filters and rules. Each list returns a dynamic set of results based on the current data and list definition.

When accessed via the API:

  1. Lists always return live results.

  2. Any change to the list definition or underlying data immediately affects API output.

The API does not allow you to create or edit lists.

Retrieve All Available Lists

You can retrieve a summary of all lists available in your Donorfy system.

  1. Send a GET request to the lists endpoint:
    ​ https://data.donorfy.com/api/v1/<apikey>/lists/

  2. Review the list metadata returned.

Each list includes:

  1. List ID.

  2. List description.

  3. List type.

  4. Row count from the last execution and the date it was run.

The row count updates automatically when list results are retrieved.

Filter Lists by Type

You can restrict results to a specific list type.

  1. Add the listType query parameter to the request:
    ​ https://data.donorfy.com/api/v1/<apikey>/lists?listType=Constituent

  2. Use a valid list type such as Constituent.

Filtering helps integrations present only relevant lists for selection.

Retrieve List Details

You can retrieve metadata for a single list when you know its ID.

  1. Send a GET request to the list detail endpoint:
    ​ https://data.donorfy.com/api/v1/<apikey>/lists/<listId>/

  2. Confirm the list configuration and metadata.

Find the List ID

You can obtain the list ID in either of these ways:

  1. Retrieve all lists via the API and select the required list.

  2. Open the list in the Donorfy UI and copy the list ID from the URL.

Retrieve List Results

List results are retrieved using a dedicated results endpoint.

  1. Send a GET request to the list results endpoint:
    ​https://data.donorfy.com/api/v1/<apikey>/lists/<listId>/results/

  2. Review the returned rows.

:For lists with very large result sets, use the asynchronous results endpoint for improved performance.

Sort List Results

You can control the order of rows returned.

  1. Add the sortBy query parameter to the request:
    ​https://data.donorfy.com/api/v1/<apikey>/lists/<listId>/results?sortBy=DateAdded

  2. Specify any field included in the list results.

📌 Note: If no sort order is specified, results are returned in EntityNumber order.

Retrieve Results in Batches

List results should always be retrieved in pages to improve performance.

  1. Use fromRow to specify the starting row:
    ​https://data.donorfy.com/api/v1/<apikey>/lists/<listId>/results?fromRow=100&numberOfRows=50

  2. Use numberOfRows to specify how many rows to return.

Batching rules:

  1. The first row index is 0.

  2. If fromRow is omitted, results start from row 0.

  3. If numberOfRows is omitted, the next 100 rows are returned.

  4. The maximum numberOfRows value is 1000.

  5. Requests beyond the end of the result set return fewer rows or none.

Sorting affects batching. Changing the sort order changes which rows appear in each batch.

Understand List Result Structure

Each row in the response is returned as a JSON object.

Every row starts with the following fields:

  1. EntityId – The unique ID of the entity.

  2. Entity – The entity type, such as Constituent or Transaction.

  3. EntityNumber – The system-assigned number for the entity.

📌 Note: You can use these values to make further API calls to retrieve full entity details.

The remaining fields vary depending on the list type and columns defined in the list.

Related Articles
Connections via the API
Activities via the API
Retrieve List Results Asynchronously
Lookups and Campaigns Using the API
Manage Gift Aid Declarations Using the API
Did this answer your question?