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

Response Name Type Notes
Header Status Int 200 if successful
Body page Int Current page that was passed in on the request
  pages Int Total number of pages available
  count Int Total number of objects available
  items Collection Collection of Mailbox fields that were requested.
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

Response Name Type Notes
Header Status Int 200 if successful
Body item   List of fields requested
Status: 200 OK
{		
	"item": {	
	        "id": 111,
	        "name": "Mailbox 1",	       
	        "folders": [{	
			  "id": 777,
			  "name": "Unassigned",
			  "type": "unassigned"						
			},		
			{	
			  "id": 888,
			  "name": "My Tickets",
			  "type": "mytickets"				
			},		
			{	
			  "id": 999,
			  "name": "Closed",
			  "type": "closed"					
			}	
		]			
	  }
}