added documentation and additional api call