---
title: Page through and search customers
slug: reference/page-through-and-search-customers
docTags:
createdAt: 2025-10-28T20:08:37.011Z
---
{
"id": "_1LfGl39MYibpJ7oGHLTs",
"type": "api-oas-v2",
"data": {
"method": "GET",
"url": "https://app.amberflo.io/customers/paging",
"servers": [
{
"url": "https://app.amberflo.io/customers/paging"
}
],
"name": "Page through and search customers",
"description": "This endpoint allows you to page through the list of customers, filter, sort and search customers.
\nFor more details, see Searching, Paging, and Sorting.
",
"contentType": "application/json",
"request": {
"pathParameters": [],
"headerParameters": [],
"queryParameters": [
{
"kind": "optional",
"name": "limit",
"type": "integer",
"description": "Maximum number of customers per page."
},
{
"kind": "optional",
"name": "page",
"type": "integer",
"description": "Page number."
},
{
"kind": "optional",
"name": "isAscending",
"type": "boolean",
"description": "Sort results in ascending order when true, descending when false. Defaults to false.
"
},
{
"kind": "optional",
"name": "sort",
"type": "string",
"description": "Which field to sort the customers by."
},
{
"kind": "optional",
"name": "search",
"type": "string",
"description": "Filter customers by searching for the provided string in customerName, customerId and customerEmail.
"
},
{
"kind": "optional",
"name": "enabled",
"type": "boolean",
"description": "If set, filter customers by their status: enabled (true) or disabled (false).
"
},
{
"kind": "optional",
"name": "idlist",
"type": "array",
"description": "Comma separated list of `customerId`s to retrieve.\n\nWhen providing this parameter, the others are ignored.",
"schema": [],
"itemType": "string",
"customType": "string[]"
},
{
"kind": "optional",
"name": "lifecycleStage",
"type": "string",
"description": "Filter customers by lifecycle stage."
},
{
"kind": "optional",
"name": "deletedCustomers",
"type": "string",
"description": "Filter customers based on their deleted state. By default deleted customers will not be included in the response.
\n\nINCLUDE - includes deleted customers in the results.EXCLUDE - does not include deleted customers in the results.ONLY - returns only deleted customers in the results.
"
},
{
"kind": "optional",
"name": "tags",
"type": "array",
"description": "Filter customers by tags. The result will include only customers that have all the tags provided.\n\nTags are indicated as :. Example: `use_case:billing`.\n\nIt is also possible to filter for tag prefixes by using the wildcard character `*`. Example: `use_case:*`.\n\nTo filter for multiple tags, separate them with a comma. Example: `use_case:billing,use_case:payment`.",
"schema": [],
"itemType": "string",
"customType": "string[]"
}
],
"bodyDataParameters": [],
"formDataParameters": [],
"oAuthParameters": [
{
"id": "apiKey",
"name": "X-API-KEY",
"kind": "optional",
"type": "apiKey",
"in": "header"
}
]
},
"responses": [
{
"statusCode": "200",
"description": "Successfully retrieved paginated customer records matching the query criteria",
"jsonExample": "",
"isExpanded": true,
"schema": [
{
"kind": "optional",
"type": "object",
"description": "Paginated response containing customer records and associated pagination metadata.",
"customType": "customer.paging.CustomerPagingResponse.out",
"schema": [
{
"name": "metadata",
"kind": "optional",
"type": "object",
"description": "Pagination metadata including filter criteria, page information, and result counts.",
"modelRef": "#/components/schemas/customer.paging.CustomerPagingMetadata.out",
"customType": "customer.paging.CustomerPagingMetadata.out",
"schema": [
{
"name": "limit",
"kind": "optional",
"type": "integer",
"description": "Maximum number of customers per page.",
"example": 0
},
{
"name": "page",
"kind": "optional",
"type": "integer",
"description": "Page number.",
"example": 0
},
{
"name": "isAscending",
"kind": "optional",
"type": "boolean",
"description": "Sort results in ascending order when true, descending when false.",
"example": ""
},
{
"name": "sort",
"kind": "optional",
"type": "string",
"description": "Which field to sort the customers by.",
"example": ""
},
{
"name": "search",
"kind": "optional",
"type": "string",
"description": "Filter customers by searching for the provided string in `customerName`, `customerId` and `customerEmail`.",
"example": ""
},
{
"name": "enabled",
"kind": "optional",
"type": "boolean",
"description": "If set, filter customers by their status: enabled (`true`) or disabled (`false`).",
"example": ""
},
{
"name": "idlist",
"kind": "optional",
"type": "array",
"description": "Comma separated list of `customerId`s to retrieve.\n\nWhen providing this parameter, the others are ignored.",
"example": "",
"itemType": "string",
"customType": "string[]",
"itemExample": "",
"itemDefault": ""
},
{
"name": "lifecycleStage",
"kind": "optional",
"type": "string",
"description": "Filter customers by lifecycle stage.",
"modelRef": "#/components/schemas/customer.CustomerLifecycleStage.out",
"customType": "customer.CustomerLifecycleStage.out",
"schema": []
},
{
"name": "deletedCustomers",
"kind": "optional",
"type": "string",
"description": "Filter customers based on their deleted state. By default deleted customers will not be included in the response.\n\n- `INCLUDE` - includes deleted customers in the results.\n- `EXCLUDE` - does not include deleted customers in the results.\n- `ONLY` - returns only deleted customers in the results.",
"modelRef": "#/components/schemas/customer.paging.DeletedCustomers.out",
"customType": "customer.paging.DeletedCustomers.out",
"schema": []
},
{
"name": "tags",
"kind": "optional",
"type": "array",
"description": "Filter customers by tags. The result will include only customers that have all the tags provided.\n\nTags are indicated as :. Example: `use_case:billing`.\n\nIt is also possible to filter for tag prefixes by using the wildcard character `*`. Example: `use_case:*`.\n\nTo filter for multiple tags, separate them with a comma. Example: `use_case:billing,use_case:payment`.",
"example": "",
"itemType": "string",
"customType": "string[]",
"itemExample": "",
"itemDefault": ""
},
{
"name": "totalRowCount",
"kind": "optional",
"type": "integer",
"description": "Total number of customers.",
"example": 0
},
{
"name": "filteredRowCount",
"kind": "optional",
"type": "integer",
"description": "Total number of customers after applying the filters.",
"example": 0
},
{
"name": "totalFilteredPages",
"kind": "optional",
"type": "integer",
"description": "Total number of pages, after applying the filters.",
"example": 0
}
]
},
{
"name": "items",
"kind": "optional",
"type": "array",
"description": "Array of customer records matching the query criteria for the current page.",
"modelRef": "#/components/schemas/customer.CustomerDetails.out",
"customType": "customer.CustomerDetails.out[]",
"schema": [
{
"name": "createTime",
"kind": "optional",
"type": "integer",
"description": "Creation time in [Unix time](https://en.wikipedia.org/wiki/Unix_time) (milliseconds)",
"example": 0
},
{
"name": "updateTime",
"kind": "optional",
"type": "integer",
"description": "Update time in [Unix time](https://en.wikipedia.org/wiki/Unix_time) (milliseconds)",
"example": 0
},
{
"name": "deleteTime",
"kind": "optional",
"type": "integer",
"description": "Timestamp when the customer was deleted, in Unix time (milliseconds). Null if not deleted.",
"example": 0
},
{
"name": "customerId",
"kind": "required",
"type": "string",
"description": "Id of the customer, as it exists in your system.",
"example": ""
},
{
"name": "customerName",
"kind": "required",
"type": "string",
"description": "Name of the customer, as it exists in your system.",
"example": ""
},
{
"name": "customerEmail",
"kind": "optional",
"type": "string",
"description": "Email of the customer, as it exists in your system.",
"example": ""
},
{
"name": "description",
"kind": "optional",
"type": "string",
"description": "Description of the customer.",
"example": ""
},
{
"name": "enabled",
"kind": "optional",
"type": "boolean",
"deprecated": true,
"description": "Warning: Deprecated\nDetermines whether the customer is active or not. Setting it to false deactivates the customer. Only relevant when updating a customer.\n\nNote that this field is superseded by the `lifecycleStage` one, which allows finer grained control. When `enabled = false` means `lifecycleStage = OFFBOARDED`, other lifecycle stages mean `enabled = true` and vice-versa.",
"example": ""
},
{
"name": "test",
"kind": "optional",
"type": "boolean",
"description": "Determines whether the customer is a test customer. Can only be set once during creation. Test customers can be excluded from certain operations.\n\nDefaults to `false`.",
"example": ""
},
{
"name": "lifecycleStage",
"kind": "optional",
"type": "string",
"description": "The lifecycle stage of a customer. The lifecycle stage of a customer determines which features of the system are enabled for it.\n\nValid lifecycle stages are:\n- `ONBOARDING` - Only usage is tracked.\n- `TRAIL` - Both usage and billing data are tracked but customer will not be charged.\n- `ACTIVE` - Both usage and billing data are tracked and customer will be charged.\n- `OFFBOARDED` - Only usage is tracked.\n\nDefault: `ACTIVE`",
"modelRef": "#/components/schemas/customer.CustomerLifecycleStage.out",
"customType": "customer.CustomerLifecycleStage.out",
"schema": []
},
{
"name": "deactivateTimeStamp",
"kind": "optional",
"type": "integer",
"description": "Timestamp when the customer was last deactivated, in Unix time (milliseconds).",
"example": 0
},
{
"name": "traits",
"kind": "optional",
"type": "map",
"description": "Reference metadata to integrate with external systems like billing.\n\nThe following traits are used by Amberflo:\n- `stripeId` for [integrating with Stripe](doc:stripe);\n- `awsm.customerIdentifier` for [integrating with AWS Marketplace](doc:associating-customers-with-aws-marketplace);\n- `currency` for the customer's currency, following the ISO standard.\n",
"example": "",
"customType": "map",
"schema": []
},
{
"name": "address",
"kind": "optional",
"type": "object",
"description": "Tax address of the customer.",
"modelRef": "#/components/schemas/customer.CustomerAddress.out",
"customType": "customer.CustomerAddress.out",
"schema": [
{
"name": "verified",
"kind": "optional",
"type": "boolean",
"description": "Indicates whether the address has been validated through the address verification system.",
"example": ""
},
{
"name": "line1",
"kind": "required",
"type": "string",
"description": "Street address line including building number and street name.",
"example": ""
},
{
"name": "state",
"kind": "optional",
"type": "string",
"description": "State or province name. Required for US addresses, optional for other countries.",
"example": ""
},
{
"name": "city",
"kind": "required",
"type": "string",
"description": "City or municipality name where the customer is located.",
"example": ""
},
{
"name": "postalCode",
"kind": "optional",
"type": "string",
"description": "Postal or ZIP code for the address. Required for US addresses, optional for other countries.",
"example": ""
},
{
"name": "country",
"kind": "required",
"type": "string",
"description": "Country name for the customer's tax address.",
"example": ""
}
]
}
]
}
],
"modelRef": "#/components/schemas/customer.paging.CustomerPagingResponse.out",
"isExpanded": true
}
]
},
{
"statusCode": "400",
"description": "Invalid query parameters, invalid sort field, or malformed filter criteria",
"jsonExample": "",
"isExpanded": true
},
{
"statusCode": "401",
"description": "Authentication required or API key is invalid",
"jsonExample": "",
"isExpanded": true
},
{
"statusCode": "403",
"description": "Insufficient permissions to access customer data",
"jsonExample": "",
"isExpanded": true
},
{
"statusCode": "500",
"description": "Internal server error occurred while querying customers",
"jsonExample": "",
"isExpanded": true
}
],
"hasXCodeSamples": false,
"examples": {
"languages": [
{
"id": "bsrxd5E_GpGEeq3bH030z",
"language": "curl",
"label": "cURL",
"code": "curl --request GET \\\n --url https://app.amberflo.io/customers/paging \\\n --header 'accept: application/json'"
},
{
"id": "QY4jr6n6q2OjFwB5JxUON",
"language": "javascript",
"label": "javascript",
"code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json\");\n\nvar requestOptions = {\n method: 'GET',\n headers: myHeaders,\n redirect: 'follow'\n};\n\nfetch(\"https://app.amberflo.io/customers/paging\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));"
},
{
"id": "MWSPhaL54Ebryq875zvVJ",
"language": "ruby",
"label": "Ruby",
"code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://app.amberflo.io/customers/paging\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Get.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\n\nresponse = https.request(request)\nputs response.read_body\n"
},
{
"id": "2I5XNvoTgAXhGYLjrvdqj",
"language": "python",
"label": "Python",
"code": "import requests\nimport json\n\nurl = \"https://app.amberflo.io/customers/paging\"\n\npayload = {}\nheaders = {\n 'accept': 'application/json',\n 'content-type': 'application/json'\n}\n\nresponse = requests.request(\"GET\", url, headers=headers, data=payload)\n\nprint(response.text)\n"
}
],
"selectedLanguageId": "bsrxd5E_GpGEeq3bH030z"
},
"results": {
"languages": [
{
"id": "8AA26v9ZYsO7OBprEcyoy",
"language": "200",
"code": "// Successfully retrieved paginated customer records matching the query criteria\n{\n \"metadata\": {\n \"limit\": \"\",\n \"page\": \"\",\n \"isAscending\": false,\n \"sort\": \"\",\n \"search\": \"\",\n \"enabled\": false,\n \"idlist\": [\n \"\"\n ],\n \"lifecycleStage\": \"\",\n \"deletedCustomers\": \"\",\n \"tags\": [\n \"\"\n ],\n \"totalRowCount\": \"\",\n \"filteredRowCount\": \"\",\n \"totalFilteredPages\": \"\"\n },\n \"items\": [\n {\n \"createTime\": \"\",\n \"updateTime\": \"\",\n \"deleteTime\": \"\",\n \"customerId\": \"\",\n \"customerName\": \"\",\n \"customerEmail\": \"\",\n \"description\": \"\",\n \"enabled\": false,\n \"test\": false,\n \"lifecycleStage\": \"\",\n \"deactivateTimeStamp\": \"\",\n \"traits\": \"\",\n \"address\": {\n \"verified\": false,\n \"line1\": \"\",\n \"state\": \"\",\n \"city\": \"\",\n \"postalCode\": \"\",\n \"country\": \"\"\n }\n }\n ]\n}"
},
{
"id": "RcPZRa3QKtza6L9PszyT_",
"language": "400",
"code": "// Invalid query parameters, invalid sort field, or malformed filter criteria\n"
},
{
"id": "WAXZw8ox-E8d7y59kvqtf",
"language": "401",
"code": "// Authentication required or API key is invalid\n"
},
{
"id": "3gYBf8oI1hOq4Nne8sjkd",
"language": "403",
"code": "// Insufficient permissions to access customer data\n"
},
{
"id": "7MGUJNBdmeI82EqauJ0I5",
"language": "500",
"code": "// Internal server error occurred while querying customers\n"
}
],
"selectedLanguageId": "8AA26v9ZYsO7OBprEcyoy"
}
},
"children": [
{
"text": ""
}
]
}