The documentation needs to improved further along with examples: 

• Correct errors, typos. 
• Enhance it further with more suitable examples
• Common use cases.
• Mention the common response being returns

Probably we need to do this after enhancing the custom fields.