finalizing logic for api calls and returns.  not tested