Developer Blog Series: Volunteer API Preview

As I'm sure many of you know, the volunteer module for Raiser's Edge includes a set of robust and powerful entities to track volunteer efforts, and Blackbaud has relied on partners and clients to build great things on top of these entities. We want to continue that tradition by delivering the Volunteer API as our next big release under the SKY API umbrella.

However, before we go too far down that line, I want to solicit feedback to ensure that we deliver the best possible experience in the top priority order for developers like you. To that end, I want to walk through our tentative plans for the Volunteer API. Hopefully this will inspire creative app ideas and constructive feedback to help us determine if we are headed down the right path with this functionality. The opportunity to improve volunteer experiences for our users is a big part of why I work at Blackbaud, so this API is particularly near and dear to my heart.

First, I will outline the entities, and then I will enumerate the endpoints that we intend to surface in a rough priority order. I encourage you to provide feedback on both aspects of the total feature set by sharing your use cases and letting us know what entities and endpoints are most important to your applications' desired functionality.

Volunteer API Entities

Volunteer Summary

Assignment

Availability

Emergency Contact

Job

Timesheet

Volunteer API Endpoints

We intend to surface full CRUD operation endpoints (POST, PATCH, and DELETE) for each entity except the Volunteer Summary entity. In addition, we intend to surface list endpoints with the standard date_added and date_modified filtering options for the Job, Timesheet, Assignment, Availability, and Interest entities. We are also exploring the option of retiring single constituent endpoints as we move forward and replacing them with constituent_id filters on the child entity list endpoints. However, the initial beta release of the Volunteer API is likely to still include single volunteer endpoints while we continue to build out the child entity lists.

In terms of priority, we will first release GET endpoints for the volunteer entities. We will surface POST operations for timesheets, assignments, and emergency contacts at the same time or shortly thereafter. Before we release POST endpoints, we will include the required code table entry endpoints to support POST operations.

GET Single Volunteer Endpoints

GET /volunteers/v1/{volunteer_id}/assignments

GET /volunteers/v1/{volunteer_id}/availability

GET /volunteers/v1/{volunteer_id}/emergency

GET /volunteers/v1/{volunteer_id}/interests

GET /volunteers/v1/{volunteer_id}/summary

GET /volunteers/v1/{volunteer_id}/timesheets

Additional GET Endpoints Required to Enable POST Endpoints

GET /volunteers/v1/volunteertypes

GET /volunteers/v1/positions

GET /volunteers/v1/jobtasks

GET /volunteers/v1/jobcategories

Initial POST Endpoints

POST /volunteers/v1/assignments

POST /volunteers/v1/timesheets

POST /volunteers/v1/emergencycontact

Additional POST operations, PATCH operations, and list endpoints are a bit farther down the line. However, this is the primary area where I would like your feedback. Which volunteer entities are the most important to you? Do you agree with the planned order for releasing endpoints? Or did we miss something? Please let me know!

Additional Endpoints

GET /volunteers/v1/interests

POST /volunteers/v1/jobs

POST /volunteers/v1/availability

POST /volunteers/v1/interests

PATCH /volunteers/v1/assignments/{assignment_id}

PATCH /volunteers/v1/availability/{availability_id}

PATCH /volunteers/v1/timesheets/{timesheet_id}

PATCH /volunteers/v1/jobs/{job_id}

DELETE /volunteers/v1/assignments/{assignment_id}

DELETE /volunteers/v1/availability/{availability_id}

DELETE /volunteers/v1/timesheets/{timesheet_id}

DELETE /volunteers/v1/jobs/{job_id}

Finally, we will create lists for all relevant entity types within the Volunteer API, much like the list endpoints that we surface in existing APIs.

Volunteer List Endpoints

GET /volunteers/v1/assignments[?date_added][&last_modified][&sort_token]

GET /volunteers/v1/availability[?date_added][&last_modified][&sort_token]

GET /volunteers/v1/emergency[?date_added][&last_modified][&sort_token]

GET /volunteers/v1/interests[?date_added][&last_modified][&sort_token]

GET /volunteers/v1/jobs[?date_added][&last_modified][&sort_token]

GET /volunteers/v1/timesheets[?date_added][&last_modified][&sort_token]

That said, we are still evaluating what a volunteer list should look like. What is the most important information to you in a list of volunteers? Is the volunteer summary information the most relevant, or is it something else?

I look forward to hearing any and all feedback that you have, and I look forward to building something great together. Thanks, and as always, happy coding!