> For the complete documentation index, see [llms.txt](https://docs.flowretail.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flowretail.com/docs/developers/api-documentation/customer/search-customers.md). # Search customers The `query` field searches on: firstName, lastName, city, postalCode, companyName, mobile, email and vatNumber.\ If `scope` is not set, customer scope is used. When mobile, email or vatNumber is specified, the according field is not searched by the query field value. ```json {"openapi":"3.0.2","info":{"title":"Flow Retail API version 2","version":"2.0.0"},"tags":[{"name":"Customer","description":"Customer"}],"servers":[{"description":"Flow Retail Production","url":"https://api.flowretail.com/v2"},{"description":"Flow Retail Stage","url":"https://api.stage.flowretail.com/v2"}],"security":[{"accessToken":[]},{"authToken":[]},{"integrationToken":[]}],"components":{"securitySchemes":{"accessToken":{"description":"Access token recevied after user login with a deviceToken","scheme":"bearer","type":"http"},"authToken":{"description":"Token received from the auth service","scheme":"bearer","type":"http"},"integrationToken":{"scheme":"bearer","type":"http"}},"parameters":{"pageNumberQuery":{"description":"Reference to a specific page in a result set.","in":"query","name":"pageNumber","required":false,"schema":{"type":"integer"}},"pageSizeQuery":{"description":"The number of items per page in a result set.","in":"query","name":"pageSize","required":false,"schema":{"type":"integer"}},"sortByQuery":{"description":"Defines which field the resource list is sorted by.","in":"query","name":"sortBy","required":false,"schema":{"type":"string"}},"sortDirectionQuery":{"description":"Reference to a sort direction","explode":false,"in":"query","name":"sortDirection","schema":{"$ref":"#/components/schemas/SortDirectionENUM"},"style":"form"}},"schemas":{"SortDirectionENUM":{"description":"|ENUM | Description |\n| ---------------- | ------------ |\n| ASC | Sort in ascending order|\n| DESC | Sort in descending order|\n","enum":["ASC","DESC"],"title":"SortDirectionENUM","type":"string"},"CustomerSearchSchema":{"title":"CustomerSearchSchema","type":"object","properties":{"exactMatch":{"type":"boolean"},"query":{"type":"string"},"mobile":{"type":"string"},"email":{"type":"string"},"scope":{"type":"array","items":{"$ref":"#/components/schemas/CustomerSearchScopeENUM"}},"customerTypes":{"type":"array","items":{"$ref":"#/components/schemas/CustomerTypeENUM"}},"vatNumber":{"type":"string"},"storeUid":{"$ref":"#/components/schemas/UID"},"customerParentUid":{"$ref":"#/components/schemas/UID"},"createdAt":{"format":"date-time","type":"string"},"customerGroupUids":{"type":"array","description":"Match customers who are members of any of these customer groups.","items":{"$ref":"#/components/schemas/UID"}},"consents":{"type":"array","description":"Filter by consent status. Each entry matches customers whose newest consent event for consentUid has the given granted value; entries AND-compose. A consent type not listed is not filtered on.","items":{"$ref":"#/components/schemas/CustomerConsentFilterSchema"}},"purchaseHistory":{"$ref":"#/components/schemas/CustomerPurchaseHistorySchema"},"hasMobile":{"type":"boolean","description":"Filter on whether the customer has a mobile number at all, as opposed to matching a specific one. true matches customers whose own mobile is set and non-empty; false matches those without one. Mobile numbers on contact rows are not considered. Omitted does not filter."},"hasEmail":{"type":"boolean","description":"Filter on whether the customer has an email address at all, as opposed to matching a specific one. true matches customers whose own email is set and non-empty; false matches those without one. Email addresses on contact rows are not considered. Omitted does not filter."}}},"CustomerSearchScopeENUM":{"description":"|ENUM | Description |\n| ---------------- | ------------ |\n| CUSTOMER | Search for customers|\n| CONTACT | Search for customer contacts|","enum":["CUSTOMER","CONTACT"],"title":"CustomerSearchScope","type":"string"},"CustomerTypeENUM":{"enum":["COMPANY","PERSON","B2B"],"title":"CustomerTypeENUM","type":"string"},"UID":{"title":"UID","type":"string","pattern":"^[A-Za-z0-9-_]+"},"CustomerConsentFilterSchema":{"title":"CustomerConsentFilterSchema","description":"A consent-status condition for customer search. Matches the customer's newest consent event for the given consent type.","type":"object","required":["consentUid","granted"],"properties":{"consentUid":{"$ref":"#/components/schemas/UID"},"granted":{"type":"boolean","description":"true matches customers whose newest event for this consent is granted; false matches those where it is not granted."}}},"CustomerPurchaseHistorySchema":{"title":"CustomerPurchaseHistorySchema","description":"Purchase-history audience condition. Product dimensions (products / product groups / categories) AND-compose, with any-of matching within each, and product matches are scoped to the activity window. Omit the whole object for no purchase-history filtering.","type":"object","properties":{"productUids":{"type":"array","description":"Match customers who have bought any of these products.","items":{"$ref":"#/components/schemas/UID"}},"productGroupUids":{"type":"array","description":"Match customers who have bought within any of these product groups (including descendants).","items":{"$ref":"#/components/schemas/UID"}},"categoryUids":{"type":"array","description":"Match customers who have bought within any of these categories (including descendants).","items":{"$ref":"#/components/schemas/UID"}},"activity":{"$ref":"#/components/schemas/CustomerPurchaseActivitySchema"}}},"CustomerPurchaseActivitySchema":{"title":"CustomerPurchaseActivitySchema","description":"Temporal purchase-history condition. When mode is TIME_RANGE, dateBasis and at least one of from / to are required and from must be <= to; from / to / dateBasis are ignored for NEVER and ANY_TIME.","type":"object","required":["mode"],"properties":{"mode":{"$ref":"#/components/schemas/CustomerPurchaseActivityModeENUM"},"dateBasis":{"description":"Which order date the range is compared against. Applies to TIME_RANGE only.","$ref":"#/components/schemas/CustomerPurchaseDateBasisENUM"},"from":{"type":"string","format":"date-time","description":"Inclusive lower bound for TIME_RANGE."},"to":{"type":"string","format":"date-time","description":"Inclusive upper bound for TIME_RANGE."},"storeUids":{"type":"array","description":"Scope the purchase history to orders placed in any of these stores. Empty or omitted means all stores.","items":{"$ref":"#/components/schemas/UID"}}}},"CustomerPurchaseActivityModeENUM":{"title":"CustomerPurchaseActivityModeENUM","description":"Discriminates the purchase-history condition.\nNEVER: customers with no matching orders. ANY_TIME: customers with at least one matching order (date-independent). TIME_RANGE: customers with a matching order inside the given date window.","enum":["NEVER","ANY_TIME","TIME_RANGE"],"type":"string"},"CustomerPurchaseDateBasisENUM":{"title":"CustomerPurchaseDateBasisENUM","description":"Which order date a purchase-activity TIME_RANGE is measured against.\nSETTLEMENT_DATE: when payment completed; excludes unpaid orders. ORDER_DATE: when the order was placed; null for OFFER/PAYMENT types and pre-field history.","enum":["ORDER_DATE","SETTLEMENT_DATE"],"type":"string"},"CustomerResponseSchema":{"title":"CustomerResponseSchema","type":"object","description":"CustomerResponseSchema","required":["address","city","companyName","countryCode","createdAt","customerUid","customerNumber","customerParentUid","customerType","email","externalId","firstname","lastModifiedAt","lastname","mobile","postalCode","pricelistUid","vatNumber","origin","addresses","contacts","extensions","consents","loyaltyId","displayName","credit","paymentTerms","internalNote","accountManager","ehf","customerGroupUids","defaultStore","relevance","preferredLanguage"],"properties":{"preferredLanguage":{"description":"The language the customer prefers to be written to in. Messages and the service portal use it, falling back to the tenant language. An empty string when the customer has no recorded preference.","allOf":[{"$ref":"#/components/schemas/LanguageCode"}]},"address":{"type":"string"},"city":{"type":"string"},"companyName":{"type":"string"},"countryCode":{"description":"ISO 3166-1: 2 characters representation of country","type":"string"},"createdAt":{"format":"date-time","type":"string"},"customerUid":{"$ref":"#/components/schemas/UID"},"customerParentUid":{"description":"References another customer, establishing it as a department under the main customer. Only applicable when customerType is COMPANY.","$ref":"#/components/schemas/OptionalUID"},"customerType":{"$ref":"#/components/schemas/CustomerTypeENUM"},"email":{"$ref":"#/components/schemas/EmailTYPE"},"externalId":{"type":"string"},"customerNumber":{"type":"string","description":"Tenant-scoped running customer number, assigned on creation. An empty string for customers created before customer numbers were enabled, or when the tenant has no customer number series."},"firstname":{"type":"string"},"lastModifiedAt":{"format":"date-time","type":"string"},"lastname":{"type":"string"},"ledgerNumber":{"type":"string","deprecated":true,"description":"Deprecated. Use ledgerNumber in accountingConfigs instead"},"mobile":{"type":"string"},"postalCode":{"type":"string"},"pricelistUid":{"$ref":"#/components/schemas/OptionalUID"},"vatNumber":{"$ref":"#/components/schemas/VatNumberTYPE"},"origin":{"type":"string"},"addresses":{"type":"array","items":{"$ref":"#/components/schemas/CustomerAddressResponseSchema"}},"contacts":{"type":"array","items":{"$ref":"#/components/schemas/CustomerContactResponseSchema"}},"extensions":{"type":"array","items":{"$ref":"#/components/schemas/CustomerExtensionResponseSchema"}},"consents":{"type":"array","items":{"$ref":"#/components/schemas/CustomerConsentStatusSchema"}},"loyaltyId":{"type":"string"},"displayName":{"type":"string"},"credit":{"$ref":"#/components/schemas/CustomerCreditResponseSchema"},"paymentTerms":{"type":"integer"},"internalNote":{"type":"string"},"accountManager":{"$ref":"#/components/schemas/AccountManagerResponseSchema"},"ehfEnabled":{"type":"boolean","description":"Deprecated: Use ehf -> enabled instead","deprecated":true},"ehf":{"$ref":"#/components/schemas/CustomerEhfResponseSchema"},"customerGroupUids":{"type":"array","items":{"$ref":"#/components/schemas/UID"}},"defaultStore":{"$ref":"#/components/schemas/CustomerStoreResponseSchema"},"representedStore":{"description":"Inter-store trade: the store this customer represents (the buyer). Only set when the INTER_STORE_TRADE extension is active.","allOf":[{"$ref":"#/components/schemas/CustomerStoreResponseSchema"}]},"relevance":{"type":"number"}}},"LanguageCode":{"title":"LanguageCode","description":"Lowercase two-letter ISO 639-1 language code, like nb, en or sv.","type":"string"},"OptionalUID":{"title":"OptionalUID","type":"string","pattern":"^[A-Za-z0-9-_]*"},"EmailTYPE":{"title":"Email","type":"string"},"VatNumberTYPE":{"description":"VAT identification number for value added tax reporting purposes.","title":"VatNumber","type":"string"},"CustomerAddressResponseSchema":{"title":"CustomerAddressResponseSchema","type":"object","required":["address","city","companyName","firstname","lastname","countryCode","email","phone","postalCode","type","customerAddressUid","displayName"],"properties":{"address":{"type":"string"},"city":{"type":"string"},"companyName":{"type":"string"},"firstname":{"type":"string"},"lastname":{"type":"string"},"countryCode":{"type":"string"},"email":{"$ref":"#/components/schemas/EmailTYPE"},"phone":{"type":"string"},"postalCode":{"type":"string"},"type":{"$ref":"#/components/schemas/CustomerAddressTypeENUM"},"customerAddressUid":{"type":"string"},"displayName":{"type":"string"}}},"CustomerAddressTypeENUM":{"enum":["DELIVERY_ADDRESS","INVOICE_ADDRESS"],"title":"CustomerAddressTypeENUM","type":"string"},"CustomerContactResponseSchema":{"title":"CustomerContactResponseSchema","type":"object","description":"CustomerContactResponseSchema","required":["firstname","lastname","email","mobile","address","postalCode","city","createdAt","lastModifiedAt","customerContactUid","extensions","displayName","role"],"properties":{"firstname":{"type":"string"},"lastname":{"type":"string"},"email":{"$ref":"#/components/schemas/EmailTYPE"},"mobile":{"type":"string"},"address":{"type":"string"},"postalCode":{"type":"string"},"city":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"lastModifiedAt":{"type":"string","format":"date-time"},"customerContactUid":{"type":"string"},"extensions":{"type":"array","items":{"$ref":"#/components/schemas/CustomerContactExtensionResponseSchema"}},"displayName":{"type":"string"},"role":{"$ref":"#/components/schemas/CustomerContactRoleENUM"}}},"CustomerContactExtensionResponseSchema":{"description":"CustomerContactExtensionResponseSchema","title":"CustomerContactExtensionResponseSchema","type":"object","properties":{"extensionCode":{"$ref":"#/components/schemas/CustomerExtensionCodeENUM"},"organizationUid":{"$ref":"#/components/schemas/UID"}},"required":["extensionCode","organizationUid"]},"CustomerExtensionCodeENUM":{"description":"|ENUM | Description |\n| ---------------- | ------------ |\n| TWO_INVOICE | The Two Invoice extension.|\n| KLAVIYO_PROFILE_ID | Klaviyo profile ID |","enum":["TWO_INVOICE","KLAVIYO_PROFILE_ID"],"title":"CustomerExtensionCodeENUM","type":"string"},"CustomerContactRoleENUM":{"title":"CustomerContactRoleENUM","type":"string","enum":["ADMIN","PURCHASER","ACCOUNTING","NONE"]},"CustomerExtensionResponseSchema":{"title":"CustomerExtensionResponseSchema","description":"CustomerExtensionResponseSchema","type":"object","required":["extensionCode","organizationUid"],"properties":{"extensionCode":{"$ref":"#/components/schemas/CustomerExtensionCodeENUM"},"organizationUid":{"$ref":"#/components/schemas/OptionalUID"}}},"CustomerConsentStatusSchema":{"title":"CustomerConsentStatusSchema","type":"object","required":["consentUid","name","status","source","createdAt"],"properties":{"consentUid":{"$ref":"#/components/schemas/UID"},"name":{"type":"string"},"status":{"type":"boolean"},"source":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"CustomerCreditResponseSchema":{"title":"CustomerCreditResponseSchema","required":["limit","balance"],"properties":{"limit":{"type":"integer"},"balance":{"type":"integer"}},"type":"object"},"AccountManagerResponseSchema":{"title":"AccountManagerResponseSchema","type":"object","required":["tenantUserUid","displayName","userCode"],"properties":{"tenantUserUid":{"$ref":"#/components/schemas/OptionalUID"},"displayName":{"type":"string"},"userCode":{"type":"string"}}},"CustomerEhfResponseSchema":{"title":"CustomerEhfResponseSchema","type":"object","required":["enabled","address"],"properties":{"enabled":{"type":"boolean","description":"EHF is enabled for this customer"},"address":{"type":"string","description":"EHF address"}}},"CustomerStoreResponseSchema":{"title":"CustomerStoreResponseSchema","type":"object","nullable":true,"required":["name","storeUid"],"properties":{"name":{"type":"string"},"storeUid":{"$ref":"#/components/schemas/UID"}}},"Paging":{"description":"totalCount The total number of items in the result set.\n\npageSize The number of items per page.\n\npageNumber The current page in the result set.","properties":{"pageNumber":{"type":"integer"},"pageSize":{"type":"integer"},"totalCount":{"type":"integer"}},"required":["totalCount","pageSize","pageNumber"],"title":"Paging","type":"object"}},"requestBodies":{"CustomerSearchRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerSearchSchema"}}}}},"responses":{"CustomerListResponse":{"content":{"application/json":{"schema":{"properties":{"items":{"items":{"$ref":"#/components/schemas/CustomerResponseSchema"},"type":"array"},"paging":{"$ref":"#/components/schemas/Paging"}},"required":["items","paging"],"type":"object"}}},"description":"CustomerListResponse"}}},"paths":{"/tenants/{tenantUid}/customers/search":{"post":{"description":"The `query` field searches on: firstName, lastName, city, postalCode, companyName, mobile, email and vatNumber. \nIf `scope` is not set, customer scope is used. \nWhen mobile, email or vatNumber is specified, the according field is not searched by the query field value.","operationId":"post-tenants-customers-search","parameters":[{"$ref":"#/components/parameters/pageNumberQuery"},{"$ref":"#/components/parameters/pageSizeQuery"},{"$ref":"#/components/parameters/sortByQuery"},{"$ref":"#/components/parameters/sortDirectionQuery"}],"requestBody":{"$ref":"#/components/requestBodies/CustomerSearchRequest"},"responses":{"200":{"$ref":"#/components/responses/CustomerListResponse"}},"summary":"Search customers","tags":["Customer"]}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.flowretail.com/docs/developers/api-documentation/customer/search-customers.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.