Field Selectors

Each endpoint returns a default set of fields based upon the given request. However, you can override this behavior by supplying one or more field selectors to explicitly request the data you need.

Example 1

Instead of returning a complete mailbox object when requesting mailboxes, you could return just the mailbox ID and name.

• REST Method: GET
• URL: https://api.helpscout.net/v1/mailboxes.json?fields=id,name

Response

Status: 200 OK
{	
	"page": 1,
	"pages": 1,
	"count": 4,
	"items": [{	
	        "id": 111,
	        "name": "Mailbox 1"	        			
	    },
	    {	
	        "id": 222,
	        "name": "Mailbox 2"	        			
	    },
	    {	
	        "id": 333,
	        "name": "Mailbox 4"	        			
	    },
	    {	
	        "id": 444,
	        "name": "Mailbox 5"	        			
	    }		
        ]	
}

Example 2

Instead of returning a complete mailbox object when getting a mailbox, you could refine the response down to certain fields AND refine the list of folders returned as well.

• REST Method: GET
• URL: https://api.helpscout.net/v1/mailboxes.json?fields=id,name,folders:(id,name,type)

Response

Status: 200 OK
{		
	"item": {	
	        "id": 111,
	        "name": "Mailbox 1",	       
	        "folders": [{	
			  "id": 777,
			  "name": "Unassigned",
			  "type": "open"
			},		
			{	
			  "id": 888,
			  "name": "Mine",
			  "type": "mine"
			},		
			{	
			  "id": 999,
			  "name": "Closed",
			  "type": "closed"					
			}	
		]			
	  }
}