{"_id":"57624356653c2d2200fec7d8","project":"55c8cff571d7580d0063a5e5","githubsync":"","parentDoc":null,"user":"55c8cf9471d7580d0063a5e4","category":{"_id":"57624356653c2d2200fec79d","project":"55c8cff571d7580d0063a5e5","__v":0,"version":"57624356653c2d2200fec79c","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-08-10T16:23:18.580Z","from_sync":false,"order":0,"slug":"documentation","title":"Getting Started"},"version":{"_id":"57624356653c2d2200fec79c","__v":21,"project":"55c8cff571d7580d0063a5e5","createdAt":"2016-06-16T06:12:38.244Z","releaseDate":"2016-06-16T06:12:38.244Z","categories":["57624356653c2d2200fec79d","57624356653c2d2200fec79e","57624356653c2d2200fec79f","57624356653c2d2200fec7a0","57624356653c2d2200fec7a1","57624356653c2d2200fec7a2","57624356653c2d2200fec7a3","57624356653c2d2200fec7a4","57624356653c2d2200fec7a5","57624356653c2d2200fec7a6","57624356653c2d2200fec7a7","57624356653c2d2200fec7a8","57624356653c2d2200fec7a9","57624356653c2d2200fec7aa","5779ca1b99b40b0e005abb3a","5779d198aea88b0e00f63277","5797d3ab17ced017003c4be4","57ac170ef1cdae0e0053cdfc","57dbfc723ed3450e00dc9e6d","5804d12d16161c0f0077df9b","5841064b652e5b0f0015a7c8","588b5e5f2966b2230009cbf9","58a68ebf3239fa0f00857619","58c23c8b4922930f0050ac91","58fd1460809fc30f00f2ee07","5934eaf5328680002d77de6a","594bf91601cfe6000f40f4c5","595c4ed696b447001ba0cf6d","596524495cee50001575f5be","5970d4f1313162004dd303b5","59780fac24dbd1001a1fa057","59a8cfd3ead78a002d63cafe","59e0323d93da1f001c9ec170","5b0c16f2be9fcb0003e28222"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"4.0.0","version":"4"},"__v":2,"updates":["57a0dd07d8313e1900454482"],"next":{"pages":[],"description":""},"createdAt":"2016-03-29T02:25:23.258Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":3,"body":"Many of our API services represent lists of objects, such as [accounts](doc:list-accounts), [extensions](doc:list-account-extensions), and [phone numbers](doc:list-account-phone-numbers).  Unless noted otherwise, they all follow common conventions for sorting, filtering, and pagination.  These features are described below.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Pagination\"\n}\n[/block]\nBecause many lists can be quite long, we feature two inputs to help with pagination: `limit` and `offset`.  These have the same meanings as used in many database engines and popular APIs:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Property\",\n    \"h-1\": \"Data Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"`limit`\",\n    \"0-1\": \"Integer\",\n    \"0-2\": \"Maximum number of objects to return in this page of results\",\n    \"1-0\": \"`offset`\",\n    \"1-1\": \"Integer\",\n    \"1-2\": \"Number of objects to skip in the result set\"\n  },\n  \"cols\": 3,\n  \"rows\": 2\n}\n[/block]\nFor example, say we are working with the [List Extensions](doc:list-account-extensions) service.  To retrieve only the first 5 results, we would add `limit=5` as a query argument, like so:\n\n    /accounts/123/extensions?limit=5\n\nTo skip the first 15 results, we would add `offset=15` as a query argument, as follows:\n\n    /accounts/123/extensions?offset=15\n\nThese parameters can be combined to provide robust pagination functionality.  The above two examples together would produce a paginated result set with 5 items per page, showing the 4th page of results:\n\n    /accounts/123/extensions?limit=5&offset=15\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Sorting\"\n}\n[/block]\nMany services provide the ability to sort the result set in various ways.  Check the documentation for each one to determine which fields are sortable.  Sorting is specified with the following syntax:\n\n    sort[<field>]=(asc|desc)\n\nFor example, to sort a [List Extensions](doc:list-account-extensions) response by ID ascending, your query would look like this:\n\n    /accounts/123/extensions?sort[id]=asc\n\nNote that this syntax allows for sorting by multiple fields.  This can be useful for more complicated result sets which we will not explain at this time.  If multiple `sort` parameters are present, they will be applied from left to right.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Fields Returned\"\n}\n[/block]\nBy default, services include a full representation of each item in the result set.  But if all you need is a list summarizing the results that were found, you can use the `fields` property to request an abbreviated version:\n\n    fields=brief\n    \nIf for some reason you need to explicitly request the full representation, you can use either of these instead:\n\n    fields=all\n    --or--\n    fields=full\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Filtering\"\n}\n[/block]\nMany services also allow filtering the result set. Check the documentation for each one to determine which fields can be used as filters.  Any number of filters are supported, and multiple filters can be specified for the same field.  Most filters allow using a very extensive range of operators too (described below.)\n\n## Syntax of Filters\n\nThere are several supported filter syntaxes.  First we demonstrate the simplest filter, which uses the implied `eq` operator to retrieve all results where <field> exactly equals <value>:\n\n    filters[<field>]=<value>\n\nFor example, to filter call logs [List Call Logs](doc:list-account-call-logs) response by call type, your query would look like this:\n\n    /accounts/123/call-logs?filters[type]=call\n\nOther operators are specified by concatenating the operator and the value with a colon, as follows:\n\n    filters[<field>]=<operator>:<value>\n    Example:  /accounts/123/call-logs?filters[type]=eq:call\n\nMultiple filters can be used on the same field, as follows. This is useful for advanced querying with operators other than `eq`:\n\n    filters[<field>]=<operator1>:<value1>&filters[<field>]=<operator2>:<value2>\n    Example:  /accounts/123/call-logs?filters[type]=call&filters[start_time]=gt:6789&sort[start_time]=asc\n\nSome operators such as `empty` don't accept any values. In this case, the colon and the value are omitted from the query:\n\n    filters[<field>]=<operator>\n    Example:  filters[name]=not-empty\n\nSome operators such as `in` accept multiple values. Use a comma-separated list in these cases:\n\n    filters[<field>]=<operator>:<value1>,<value2>,<value3>\n    Example: filters[npa]=in:732,201,917\n    \n## Operators\n\nHere are the filter operators supported by most of our list-based services. Note that some services only support a subset of operators. Check the documentation for each service to be sure.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Operator\",\n    \"h-1\": \"Description and Example\",\n    \"h-2\": \"\",\n    \"0-0\": \"`empty`\",\n    \"1-0\": \"`not-empty`\",\n    \"2-0\": \"`eq`\",\n    \"3-0\": \"`ne`\",\n    \"4-0\": \"`lt`\",\n    \"5-0\": \"`gt`\",\n    \"6-0\": \"`lte`\",\n    \"7-0\": \"`gte`\",\n    \"8-0\": \"`starts-with`\",\n    \"9-0\": \"`ends-with`\",\n    \"10-0\": \"`contains`\",\n    \"11-0\": \"`not-starts-with`\",\n    \"12-0\": \"`not-ends-with`\",\n    \"13-0\": \"`not-contains`\",\n    \"14-0\": \"`between`\",\n    \"15-0\": \"`not-between`\",\n    \"17-0\": \"`not-in`\",\n    \"16-0\": \"`in`\",\n    \"0-1\": \"Empty field. Includes values of 0, empty string, or null. `filters[name]=empty`\",\n    \"1-1\": \"Non-empty field. `filters[name]=not-empty`\",\n    \"2-1\": \"Equal to the value. `filters[id]=eq:7890`\",\n    \"3-1\": \"Not equal to the value. `filters[id]=ne:7890`\",\n    \"4-1\": \"Less than the value. `filters[year]=lt:2010`\",\n    \"5-1\": \"Greater than the value. `filters[year]=gt:2010`\",\n    \"6-1\": \"Less than or equal to the value. `filters[year]=lte:2010`\",\n    \"7-1\": \"Greater than or equal to the value. `filters[year]=gte:2010`\",\n    \"8-1\": \"String begins with the value. `filters[name]=starts-with:Fred`\",\n    \"9-1\": \"String ends with the value. `filters[name]=ends-with:Smith`\",\n    \"10-1\": \"String contains the value. `filters[name]=contains:Acme`\",\n    \"11-1\": \"String doesn't begin with the value. `filters[name]=not-starts-with:Fred`\",\n    \"12-1\": \"String doesn't end with the value. `filters[name]=not-ends-with:Smith`\",\n    \"13-1\": \"String doesn't contain the value. `filters[name]=not-contains:Acme`\",\n    \"14-1\": \"Number is within a range. `filters[year]=between:2005,2010`\",\n    \"15-1\": \"Number isn't within a range. `filters[year]=not-between:2005,2010`\",\n    \"16-1\": \"Value is in a given list. `filters[npa]=in:402,909,316`\",\n    \"17-1\": \"Value isn't in a given list. `filters[npa]=not-in:402,909,316`\",\n    \"0-2\": \"\",\n    \"1-2\": \"\",\n    \"2-2\": \"\",\n    \"3-2\": \"\",\n    \"4-2\": \"\",\n    \"5-2\": \"\",\n    \"6-2\": \"\",\n    \"7-2\": \"\",\n    \"8-2\": \"\",\n    \"9-2\": \"\",\n    \"10-2\": \"\",\n    \"11-2\": \"\",\n    \"12-2\": \"\",\n    \"13-2\": \"\",\n    \"14-2\": \"\",\n    \"15-2\": \"\",\n    \"16-2\": \"\",\n    \"17-2\": \"\",\n    \"h-3\": \"Example\",\n    \"0-3\": \"\",\n    \"1-3\": \"\",\n    \"2-3\": \"\",\n    \"3-3\": \"\",\n    \"4-3\": \"\",\n    \"5-3\": \"\",\n    \"6-3\": \"\",\n    \"7-3\": \"\",\n    \"8-3\": \"\",\n    \"9-3\": \"\",\n    \"10-3\": \"\",\n    \"11-3\": \"\",\n    \"12-3\": \"\",\n    \"13-3\": \"\",\n    \"14-3\": \"\",\n    \"15-3\": \"\",\n    \"16-3\": \"\",\n    \"17-3\": \"\",\n    \"18-0\": \"`only`\",\n    \"18-1\": \"Combine with the `deleted` filter, to list only deleted items.\\n`filters[deleted]=only`\",\n    \"19-0\": \"`ignore`\",\n    \"19-1\": \"Combine with the `deleted` filter, to list only existing item.\\n`filters[deleted]=ignore`\",\n    \"20-0\": \"`with`\",\n    \"20-1\": \"Combine with the `deleted` filter, to list both deleted and existing items.\\n`filters[deleted]=with`\"\n  },\n  \"cols\": 2,\n  \"rows\": 21\n}\n[/block]","excerpt":"","slug":"list-inputs","type":"basic","title":"List Inputs"}
Many of our API services represent lists of objects, such as [accounts](doc:list-accounts), [extensions](doc:list-account-extensions), and [phone numbers](doc:list-account-phone-numbers). Unless noted otherwise, they all follow common conventions for sorting, filtering, and pagination. These features are described below. [block:api-header] { "type": "basic", "title": "Pagination" } [/block] Because many lists can be quite long, we feature two inputs to help with pagination: `limit` and `offset`. These have the same meanings as used in many database engines and popular APIs: [block:parameters] { "data": { "h-0": "Property", "h-1": "Data Type", "h-2": "Description", "0-0": "`limit`", "0-1": "Integer", "0-2": "Maximum number of objects to return in this page of results", "1-0": "`offset`", "1-1": "Integer", "1-2": "Number of objects to skip in the result set" }, "cols": 3, "rows": 2 } [/block] For example, say we are working with the [List Extensions](doc:list-account-extensions) service. To retrieve only the first 5 results, we would add `limit=5` as a query argument, like so: /accounts/123/extensions?limit=5 To skip the first 15 results, we would add `offset=15` as a query argument, as follows: /accounts/123/extensions?offset=15 These parameters can be combined to provide robust pagination functionality. The above two examples together would produce a paginated result set with 5 items per page, showing the 4th page of results: /accounts/123/extensions?limit=5&offset=15 [block:api-header] { "type": "basic", "title": "Sorting" } [/block] Many services provide the ability to sort the result set in various ways. Check the documentation for each one to determine which fields are sortable. Sorting is specified with the following syntax: sort[<field>]=(asc|desc) For example, to sort a [List Extensions](doc:list-account-extensions) response by ID ascending, your query would look like this: /accounts/123/extensions?sort[id]=asc Note that this syntax allows for sorting by multiple fields. This can be useful for more complicated result sets which we will not explain at this time. If multiple `sort` parameters are present, they will be applied from left to right. [block:api-header] { "type": "basic", "title": "Fields Returned" } [/block] By default, services include a full representation of each item in the result set. But if all you need is a list summarizing the results that were found, you can use the `fields` property to request an abbreviated version: fields=brief If for some reason you need to explicitly request the full representation, you can use either of these instead: fields=all --or-- fields=full [block:api-header] { "type": "basic", "title": "Filtering" } [/block] Many services also allow filtering the result set. Check the documentation for each one to determine which fields can be used as filters. Any number of filters are supported, and multiple filters can be specified for the same field. Most filters allow using a very extensive range of operators too (described below.) ## Syntax of Filters There are several supported filter syntaxes. First we demonstrate the simplest filter, which uses the implied `eq` operator to retrieve all results where <field> exactly equals <value>: filters[<field>]=<value> For example, to filter call logs [List Call Logs](doc:list-account-call-logs) response by call type, your query would look like this: /accounts/123/call-logs?filters[type]=call Other operators are specified by concatenating the operator and the value with a colon, as follows: filters[<field>]=<operator>:<value> Example: /accounts/123/call-logs?filters[type]=eq:call Multiple filters can be used on the same field, as follows. This is useful for advanced querying with operators other than `eq`: filters[<field>]=<operator1>:<value1>&filters[<field>]=<operator2>:<value2> Example: /accounts/123/call-logs?filters[type]=call&filters[start_time]=gt:6789&sort[start_time]=asc Some operators such as `empty` don't accept any values. In this case, the colon and the value are omitted from the query: filters[<field>]=<operator> Example: filters[name]=not-empty Some operators such as `in` accept multiple values. Use a comma-separated list in these cases: filters[<field>]=<operator>:<value1>,<value2>,<value3> Example: filters[npa]=in:732,201,917 ## Operators Here are the filter operators supported by most of our list-based services. Note that some services only support a subset of operators. Check the documentation for each service to be sure. [block:parameters] { "data": { "h-0": "Operator", "h-1": "Description and Example", "h-2": "", "0-0": "`empty`", "1-0": "`not-empty`", "2-0": "`eq`", "3-0": "`ne`", "4-0": "`lt`", "5-0": "`gt`", "6-0": "`lte`", "7-0": "`gte`", "8-0": "`starts-with`", "9-0": "`ends-with`", "10-0": "`contains`", "11-0": "`not-starts-with`", "12-0": "`not-ends-with`", "13-0": "`not-contains`", "14-0": "`between`", "15-0": "`not-between`", "17-0": "`not-in`", "16-0": "`in`", "0-1": "Empty field. Includes values of 0, empty string, or null. `filters[name]=empty`", "1-1": "Non-empty field. `filters[name]=not-empty`", "2-1": "Equal to the value. `filters[id]=eq:7890`", "3-1": "Not equal to the value. `filters[id]=ne:7890`", "4-1": "Less than the value. `filters[year]=lt:2010`", "5-1": "Greater than the value. `filters[year]=gt:2010`", "6-1": "Less than or equal to the value. `filters[year]=lte:2010`", "7-1": "Greater than or equal to the value. `filters[year]=gte:2010`", "8-1": "String begins with the value. `filters[name]=starts-with:Fred`", "9-1": "String ends with the value. `filters[name]=ends-with:Smith`", "10-1": "String contains the value. `filters[name]=contains:Acme`", "11-1": "String doesn't begin with the value. `filters[name]=not-starts-with:Fred`", "12-1": "String doesn't end with the value. `filters[name]=not-ends-with:Smith`", "13-1": "String doesn't contain the value. `filters[name]=not-contains:Acme`", "14-1": "Number is within a range. `filters[year]=between:2005,2010`", "15-1": "Number isn't within a range. `filters[year]=not-between:2005,2010`", "16-1": "Value is in a given list. `filters[npa]=in:402,909,316`", "17-1": "Value isn't in a given list. `filters[npa]=not-in:402,909,316`", "0-2": "", "1-2": "", "2-2": "", "3-2": "", "4-2": "", "5-2": "", "6-2": "", "7-2": "", "8-2": "", "9-2": "", "10-2": "", "11-2": "", "12-2": "", "13-2": "", "14-2": "", "15-2": "", "16-2": "", "17-2": "", "h-3": "Example", "0-3": "", "1-3": "", "2-3": "", "3-3": "", "4-3": "", "5-3": "", "6-3": "", "7-3": "", "8-3": "", "9-3": "", "10-3": "", "11-3": "", "12-3": "", "13-3": "", "14-3": "", "15-3": "", "16-3": "", "17-3": "", "18-0": "`only`", "18-1": "Combine with the `deleted` filter, to list only deleted items.\n`filters[deleted]=only`", "19-0": "`ignore`", "19-1": "Combine with the `deleted` filter, to list only existing item.\n`filters[deleted]=ignore`", "20-0": "`with`", "20-1": "Combine with the `deleted` filter, to list both deleted and existing items.\n`filters[deleted]=with`" }, "cols": 2, "rows": 21 } [/block]