Foundation Data & Integrations
JSON REST API
GET Request - Retrieving records
19 min
get requests allow you to retrieve information from the system, either in bulk or for a single record the api also allows information from related tables to be included in the response url format single record the format to retrieve a single record is https //\[instance url]/v1/\[table name]/\[record id] example https //sandbox servicely ai/v1/incident/8291a83ece8811ebb1870242ac14001a https //sandbox servicely ai/v1/incident/8291a83ece8811ebb1870242ac14001a multiple records the format to retrieve a list of records is https //\[instance url]/v1/\[table name] example https https //sandbox servicely ai/v1/incident https //sandbox servicely ai/v1/incident example get single record ➜ https https //sandbox servicely ai/v1/incident/8291a83ece8811ebb1870242ac14001a http/1 1 200 ok content encoding gzip content length 618 content type application/json x rate limit cost 1 x result count 0 x result more false x total result count 0 { "data" { "assignmentgroup" "c0a8016c682a17a381682a2b5c7b000a", "classification" "c0a805c8685e1cde81685e406ffd325f", "closed" false, "createdby" "4028818a3b214291013b21504a000000", "createdon" "2021 06 16t09 52 33 544z", "email" "eric employee\@servicely ai", example multiple record query ➜ https sandbox servicely ai/v1/incident http/1 1 200 ok content encoding gzip content length 757 content type application/json x page 1 x page size 200 x rate limit cost 2 x result count 2 x result more false x total result count 2 { "data" \[ { "assignmentgroup" "c0a8016c682a17a381682a2b5c7b000a", "classification" "c0a805c8685e1cde81685e406ffd325f", "closed" false, "createdby" "4028818a3b214291013b21504a000000", "urgency" "medium", "version" 2, "workflowstatus" "new", "id" "70a88bdace8811ebb1870242ac14001a" }, { "assignmentgroup" "c0a8016c682a17a381682a2b5c7b000a", "classification" "c0a805c8685e1cde81685e406ffd325f", "closed" false, "createdby" "4028818a3b214291013b21504a000000", "urgency" "high", "version" 4, "workflowstatus" "new", "id" "8291a83ece8811ebb1870242ac14001a" } ] } simple query simple equality queries can be performed by setting the fieldname and required value as url query parameters ➜ https v sandbox servicely ai/v1/incident workflowstatus==new get /v1/incident?workflowstatus=new http/1 1 http/1 1 200 ok content encoding gzip content length 624 content type application/json x page 1 x page size 200 x rate limit cost 1 x result count 1 x result more false x total result count 1 { "data" \[ { "assignmentgroup" "c0a8016c682a17a381682a2b5c7b000a", "classification" "c0a805c8685e1cde81685e406ffd325f", "closed" false, "urgency" "medium", "version" 2, "workflowstatus" "new", "id" "70a88bdace8811ebb1870242ac14001a" } ] } limit fields the returned fields can be controlled by passing a comma delimited set of field names in the ‘ fields ’ url query parameter this applies to both single and multiple results ➜ https https //sandbox servicely ai/v1/incident/8291a83ece8811ebb1870242ac14001a fields==id,workflowstatus,shortdescription,assignmentgroup http/1 1 200 ok content encoding gzip content length 183 content type application/json x rate limit cost 1 x result count 0 x result more false x total result count 0 { "data" { "assignmentgroup" "c0a8016c682a17a381682a2b5c7b000a", "shortdescription" "example incident 2", "workflowstatus" "work in progress", "id" "8291a83ece8811ebb1870242ac14001a" } } ordering results can be sorted by passing an ‘order’ or ‘order desc’ query parameter with the name of the field to order by ➜ https demo servicely ai/v1/user order==username fields==username http/1 1 200 ok { "data" \[ { "username" "admin" }, { "username" "andrew\ venn" }, { "username" "benlinus" }, { "username" "charliepace" }, ➜ https demo servicely ai/v1/user order desc==username fields==username http/1 1 200 ok { "data" \[ { "username" "trial admin" }, { "username" "sysuser" }, { "username" "sofi" }, { include displayvalues some fields have a database value and a display value to include both, you can specify the field in the displayvalues argument ➜ https https //sandbox servicely ai/v1/incident fields==number displayvalues==classification,assignmentgroup http/1 1 200 ok x total result count 2 { "data" \[ { "assignmentgroup" { "displayvalue" "support", "value" "c0a8016c682a17a381682a2b5c7b000a" }, "classification" { "displayvalue" "other", "value" "c0a805c8685e1cde81685e406ffd325f" }, "number" "inc0000003" }, include relationship information by default, only data directly associated with the records being retrieved are returned (i e direct fields and the values of one to x relationships) to return information from the target of the relationship, specify the relations argument with a comma delimited list of relation names ➜ https https //sandbox servicely ai/v1/incident relations==assignmentgroup name fields==id,shortdescription http/1 1 200 ok content encoding gzip content length 200 content type application/json x page 1 x page size 200 x rate limit cost 4 x result count 2 x result more false x total result count 2 { "data" \[ { "assignmentgroup" { "name" "support", "id" "c0a8016c682a17a381682a2b5c7b000a" }, "shortdescription" "example incident", "id" "70a88bdace8811ebb1870242ac14001a" }, nested relationship information nested relations can also be retrieved as part of a get query the following example retrieves the name of the requestor, and also the name and id of their manager ➜ https https //sandbox servicely ai/v1/incident relations==requestor name,requestor manager name fields==id,shortdescription http/1 1 200 ok content encoding gzip content length 250 content type application/json x page 1 x page size 200 x rate limit cost 5 x result count 2 x result more false x total result count 2 { "data" \[ { "requestor" { "manager" { "name" "andrew venn", "id" "402881923a065eed013a06621fff0001" }, "name" "erik employee", "id" "c0a8011645fb1a608145fb3102b10000" }, "shortdescription" "example incident", "id" "70a88bdace8811ebb1870242ac14001a" }, paging results results can be paged by passing the page and page size arguments the command below returns 2 rows from the 5th page of the user table ➜ https https //sandbox servicely ai/v1/user page size==2 page==5 fields==id,name http/1 1 200 ok content encoding gzip content length 143 content type application/json date wed, 16 jun 2021 11 29 27 gmt x page 5 x page size 2 x rate limit cost 2 x result count 2 x result more true x total result count 14 { "data" \[ { "name" "andrew venn", "id" "402881923a065eed013a06621fff0001" }, { "name" "hr agent", "id" "c0a800046b2a15c6816b2a27dd1c0079" } ] } result headers the page results also return the total result count and page information in the http headers x page 2 # 'page' number 2 which would be records 6 to 10 with a page size of 5 record x page size 5 # the page size used x result count 5 # the number of results returned a value less than the page size would indicate the end of the records has been reached x total result count 14 # the number of records in total in the data set complex queries complex queries can be achieved by passing a json formatted query string to the ‘query’ parameter the format consists of a json object with a conjunction (and, or, nor) followed by an array of criterions (which can also be conjunctions) the json str { "and" \[ { "fieldname" "priority", "operator" "in", "value" \["1", "2"] }, { "fieldname" "closed", "operator" "=", "value" true } ] } conjunction description and all criteria in the array must match or any of the criteria in the array can match nor none of the criteria in the array can match operators description arity startswith the string value starts with this term 1 = the value equals this term 1 != the value is not equal to this term (does not apply to null values) 1 contains the string value contains this term 1 doesnotcontain the string value does not contain this term 1 isempty the value is empty (i e null) 0 isnotempty the value is not empty (i e not null) 0 in the value is one of the supplied terms many notin the value is not one of the supplied terms many < the value is less than the supplied term 1 > the value is greater than the supplied term 1 <= the value is less than or equal to the supplied term 1 >= the value is greater than or equal to the supplied term 1 between the value is between the two supplied terms 2 example to simplify the encoding of the json query, we will place that in a text file for testing query json { "and" \[ { "fieldname" "active", "operator" "=", "value" true }, { "fieldname" "email", "operator" "isnotempty" } ] } query json and execute using httpie ➜ https demo servicely ai/v1/user fields==email,active query==@query json http/1 1 200 ok content encoding gzip content type application/json x page 1 x page size 200 x rate limit cost 11 x response time 115 x result count 11 x result more false x total result count 11 { "data" \[ { "active" true, "email" "test\@gmail com" }, { "active" true, "email" "test\@servicely ai" }, { "active" true, "email" "test23\@servicely ai" }, dot walk queries queries can also filter through relationships for example, find all users through the manager relationship, using the managers email address { "and" \[ { "fieldname" "manager email", "operator" "=", "value" "andrew\ venn\@servicely ai" } ] } query json ➜ https demo servicely ai/v1/user fields==email,active query==@query json http/1 1 200 ok content encoding gzip content type application/json x page 1 x page size 200 x rate limit cost 1 x response time 44 x result count 1 x result more false x total result count 1 { "data" \[ { "active" true, "email" "test user\@servicely ai" } ] } tip copying queries from the ui when developing queries, it is much easier to use the list query builder in the application an copy the query for use in the integration by default, the copy button copies a browser link to the query in the application by using modifier keys when clicking the ‘copy’ button, you can get the query in formats suitable for use in integrations modifier name description none link copy url link to the page/query in the application to the clipboard shift api link copy url link to the rest api version of the query to the clipboard meta formatted json copy the pretty formatted json query to the clipboard meta+shift raw json copy the raw json query to the clipboard alt+meta command line json copy the raw json string formatted for use from the command line