Clarification needed on Users by role(s) /UserRead Model

Byron Avila

Hello everyone,

I’m starting to work on the Education Management side of things and using the API to pull users by role: API Reference.

So far, I’ve been successful in fetching all students using the student role. However, I noticed the documentation mentions a UserRead collection. Does this need to be enabled in some way to access those extra fields? I don’t see how it’s fetched.

Here’s what I’m using in Python:

url = f"{BASE_URL}/v1/users?roles={role_id}"

I also saw the extended users by role endpoint, but that returns way more data than I need right now.

My questions:

• What do these definitions, including UserRead, actually mean?
• How do I enable or fetch those fields when needed?

Thanks in advance for any guidance!

Brian Gray

The UserRead collection is the name of the data package returned by the call to User Get (by role or by ID). It includes a count of the number of users returned, a link to the next "page" of data (if there is a next page), and an array of the user data objects.

See the https://developer.sky.blackbaud.com/api#api=school&operation=v1usersget page (which is probably the documentation you're referring to). At the top of the page, you can sign into the the page and use the Try It button to interact directly with the API - to see the returned data or an error message. At the top of the page, in the Documentation menu you will find a link to the Getting Started page, which will take you through the process of doing the initial work to allow API access to your data.

Byron Avila

@Brian Gray Thanks for the quick response. I completed all the get-started guides and successfully used the 'Users by role(s)' request; however, I only received the default fields in the JSON object.

Clarifying my question, under the UserRead Model, there are other fields like "gender" that are not included in the default response. How can I get those values? Below is the first entry of a student on the first page (date is a replica of a student's response for privacy). I want to be able to access those other fields listed under the UserRead Model.

{    "id": 524872,    "deceased": false,    "display": "Joe, Odessa '26",    "email": "olman@ae.org",    "email_active": true,    "first_name": "Odessa",    "last_name": "Gelman",    "lost": false,    "maiden_name": "",    "middle_name": "Su'ad",    "nick_name": "Odessa",    "preferred_name": "Odessa",    "preferred_last_name": "",    "dob": "2008-03-25T00:00:00+00:00",    "prefix": "",    "suffix": "",    "home_languages": []  },

Below is "gender" listed under the UserRead Model as an example. Thank you!

Brian Gray

It appears to me like you are looking at documentation in another part of the API. The User Get by Role end-point in the School API (developer.sky.blackbaud.com/api#api=school&operation=v1usersget) includes these fields in the response:

User Extended Get (developer.sky.blackbaud.com/api#api=school&operation=V1UsersExtendedGet) includes gender (and lots of other stuff).

There is no option to request that specific fields are included or excluded in the response. You get all of the data listed for each user.

Note that User Get by Role uses the Role ID, and User Extended Get by Role uses the Base Role ID. They are different values. See developer.sky.blackbaud.com/api#api=school&operation=v1rolesget.

My understanding is that Base Role IDs are constant from school to school, but the role ID values could be different. I don't know that for certain, but you should verify the values for your school.

For my school, the "Student" role has base role ID 14 and role ID 17426.

Byron Avila

Thank you@Brian Gray. That's super helpful. I think I was misguided because these other fields are listed on the same page. Why list them there if they are part of the response?

I will play around with User Extended Get. Thanks again!

Stephen Boyle

https://community.blackbaud.com/discussion/comment/307206#Comment_307206

Base role ID is also constant for all clones of the role. E.g. if Substitute is a clone of Teacher, they'd both have a base role ID of 15 (and yes base role IDs are constant across schools as well).

These two endpoints were created before my time. The response output likely simply delivers exactly what is delivered by the internal stored procedures, and the dev used the same object model for both despite it not really fitting for the 'by roles' version.

Eric Eskildsen

https://community.blackbaud.com/discussion/comment/307215#Comment_307215

Good callout. This looks like a bug.

The OpenAPI schema says /v1/users returns a collection of UserRead models. But the actual responses are missing gender and a number of other UserRead properties.

@Stephen Boyle

Eric Eskildsen

@Byron Avila

To share my experience just as one more data point among many to consider here, we almost never use /v1/users. We almost always use /v1/users/extended.

An advantage of /v1/users/extended is filtering by base role, which as Brian and Stephen mentioned is constant across schools. E.g., to get students, teachers, and non-teaching staff, you would filter by base role IDs 14, 15, and 332, respectively.

/v1/users/extended also has properties that we typically need when making these calls, while /v1/users is limited, as you saw.

Byron Avila

Thanks, @Eric Eskildsen.

I started using it as recommended. I appreciate the insight.