Sort_token for beginners

Stephen Crush

I am fairly new to blackbaud and I am trying to understand how the sort_token works. Using the below api as an example I had initial fun passing date_modified rather than last_modified and could not figure out why was returning data but not looking at the date_modified column. Now using last_modified in the call I can see dates look to be correct in the initial call and now automatically get sort_token I think rather than offset in the next_link. My question is how is sort_token used alongside the date?

For the first ever call would I pass the sort_token parameter with nothing alongside last_modified?

How do the calls differ regarding making a call today and then three days later getting the next records from the database - for instance if I pulled 200 records I may get all 200 with the same date and would then be passing that same date in next call but would not want the same 200 records again (date_modified seems to have been done in batches). Would I have to save the sort_token returned and then a few days later pass that alongside date and would that work, is that enough?

How does the process work if pulling thousands of records? Does it automatically use the sort_token and only when make a later call would need to use latest sort_token? Is anything else required such as sort? Thanks, hope makes sense...
https://api.sky.blackbaud.com/constituent/v1/addresses

Ben Regier

For the first call, you use the last_modified field to tell Blackbaud that you want to see all changes that have happened since this date.


Blackbaud sends you the first batch of changes, and includes a sort_token. The sort token is a way of saving your query AND saving your place in the query. So in effect, it's a way for Blackbaud to remember that you had asked to see all changes since a specific date, and also to remember how many of those changes it has already sent to you.


After you receive your sort_token, you use it in subsequent calls instead of the last_modified field. (Just to be sure it's clear, you do not use the sort_token alongside last_modified, because your initial query, which included the last_modified date, is included in your sort_token.) Blackbaud will send you the next batch of modified records, along with a new sort_token. Once again, you save that sort_token so that the next time you make a call, Blackbaud can continue from where it left off.


It doesn't matter how long you wait in between calls - the sort_token ensures that all changes will be sent, and that no change will be sent more than once.