Query API Provides Developers with New Options for Data Extraction

Query API for Raiser’s Edge NXT is now in public preview and includes new endpoints for building, executing, and retrieving query data. The API is released as a package, with the Query web view feature currently in a customer early access program (EAP), with a planned release for this spring, pending feedback from the community. The API can perform any functions currently supported by the web view feature.



The API is released as a package, with the Query web view feature currently in a customer EAP, with a planned release for this spring, pending feedback from the community. The API can perform any functions currently supported by the web view feature.



While the API does work with both Raiser’s Edge NXT and Blackbaud Financial Edge NXT® Query, at this time only the Raiser’s Edge NXT SKY Developer cohort has been enabled. We anticipate a release for Financial Edge NXT this spring and will inform you when it is available for developers and partners.

Getting Started with Query API:

Pro-code developers and partners
The Query API is in the Raiser’s Edge NXT SKY Developer Cohort or in your partner sandbox environment. Any user with permission to use Query in Raiser’s Edge NXT database view may authenticate to access Query API. Developers working in the cohort environment have already been granted permission to use Query.

Low-code developers
You can access a pre-built template to utilize the Query API with the Microsoft Power Platform SKY Add-ins Connector. Extract query data from Raiser’s Edge NXT by Query ID and store it as a CSV file in OneDrive or SharePoint. This is helpful for reporting scenarios with Microsoft Power BI where data was not accessible via the custom connector.

Query API Best Practices:
Below are some recommended best practices to maximize results with Query API:

1. SKY APIs for GET list endpoints, such as GET Constituent List, are still the most performant and efficient ways to extract bulk data from Raiser’s Edge NXT. This method should always be prioritized when the required data is accessible from this type of API endpoint.
   .
2. Do not poll the Query job status more frequently than once every 30 seconds for non-real-time background processes. If you are using the API in an interactive scenario and need to limit interactive end-user wait times, then do not poll more frequently than once every 5 seconds.
   .
3. Data extracted via the Query API should be treated with the same level of sensitivity as you treat data that you extract using any other API. Be mindful of the need to secure any data that you extract from the Blackbaud system and store in your own systems. Once the data leaves the Blackbaud system and is stored in your system, it will be subject to the data security controls that you implement and will be outside the scope and authority of the Blackbaud hosting security controls. This concept applies to any data you extract using SKY API, so it is not a new concept for Query. However, it is worth reminding you of this responsibility so that you can be thoughtful with how you process and store query results.
   .
4. The URI returned by the Query Execution Job API, which is used to download results, should be treated as a confidential credential. During the query EAP the URI expires 15 minutes from the time you receive the Query job result, however prior to GA this may be adjusted. The URI should be used immediately after it is obtained using a code flow of getting the URI, downloading the result, and discarding the URI value (set any variables holding the value to null or blank). The expiration period for the URI is intended to support this tight control flow of a few minutes between fetching the URI and downloading from it. The URI serves as a secure credential to access the query result, and thus should be considered a secret unique value. Sharing this URI with anyone is strongly discouraged, and as a best practice, avoid persisting the URI beyond processing the job result. The typical pattern for using the Query API involves calling the Query Execution Job API to obtain the URI, downloading the results using the URI, and then discarding the URI.

Providing feedback:
We also encourage you to ask questions and leave feedback in Blackbaud Community, and to submit all ideas for improvement to the API or the documentation in our Idea Bank. There is a new Idea Bank category available specifically for the Query API.
.