Skip to main content

Searching for customers

info

This recipe assumes you've already familiarized yourself with the Core API getting started , Authentication, and Error Handling pages.

Overview

To search for customers, we provide the searchCustomers query.

This query supports pagination and returns a CustomerSearchConnection object.

In order to search, you use the searchQuery parameter in searchCustomers, which consists of a group of search conditions.

You can provide as many as 15 different search conditions. Each CustomerSearchCondition) consists of:

  1. the Customer attribute you want your condition to be applied on: fullName, shortName, email or externalId
  2. the search expression (StringSearchExpression) to use to match this attribute

Permissions

The searchCustomers query requires the following permission: customer:search.

Search queries

Before you try to search, please make sure you create at least one customer in Plain. You can use the Upserting a customer recipe to create it.

The query we will use for all the examples below is the same:

query searchCustomers($searchQuery: CustomersSearchQuery!) {
searchCustomers(searchQuery: $searchQuery) {
edges {
node {
id
externalId
shortName
fullName
email {
email
}
}
}
}
}
note

The Customer Object has more fields you can select, but in this recipe we're only selecting a few important ones.

Searching for customers by full and short name

We are going to search for customers whose name (full or short) contain the word carL.

Variables

{
"searchQuery": {
"or": [
{
"fullName": {
"caseInsensitiveContains": "carl"
}
},
{
"shortName": {
"caseInsensitiveContains": "carl"
}
}
]
}
}

Response

{
"data": {
"searchCustomers": {
"edges": [
{
"node": {
"id": "c_XXXXXXXXXXXXXXXXXXXXXXXXXX",
"externalId": "cus_98f1",
"shortName": "Carlos",
"fullName": "Carlos Pérez",
"email": {
"email": "c.perez@example.com"
}
}
},
{
"node": {
"id": "c_YYYYYYYYYYYYYYYYYYYYYYYYYY",
"externalId": "cus_2",
"shortName": "Carl",
"fullName": "Carl Smith",
"email": {
"email": "carl.s@company.org"
}
}
}
]
}
}
}

Searching for customers by email

Search for customers whose email contains @company.org.

Variables

{
"searchQuery": {
"or": [
{
"email": {
"caseInsensitiveContains": "@company.org"
}
}
]
}
}

Response

{
"data": {
"searchCustomers": {
"edges": [
{
"node": {
"id": "c_YYYYYYYYYYYYYYYYYYYYYYYYYY",
"externalId": "cus_2",
"shortName": "Carl",
"fullName": "Carl Smith",
"email": {
"email": "carl.s@company.org"
}
}
}
]
}
}
}

Searching for customers by externalId

Search for customers with an externalId containing our internal id cus_98f1.

Variables

{
"searchQuery": {
"or": [
{
"externalId": {
"caseInsensitiveContains": "cus_98f1"
}
}
]
}
}

Response

{
"data": {
"searchCustomers": {
"edges": [
{
"node": {
"id": "c_XXXXXXXXXXXXXXXXXXXXXXXXXX",
"externalId": "cus_98f1",
"shortName": "Carlos",
"fullName": "Carlos Pérez",
"email": {
"email": "c.perez@example.com"
}
}
}
]
}
}
}

Searching for customers with different attributes

You are free to use any combination of search conditions (on the same field or different fields). In this example, we want to search for customers with full names containing smith, david, louisa or carlos. As well as customers using example in their email address.

Variables

{
"searchQuery": {
"or": [
{
"fullName": {
"caseInsensitiveContains": "smith"
}
},
{
"fullName": {
"caseInsensitiveContains": "david"
}
},
{
"fullName": {
"caseInsensitiveContains": "louisa"
}
},
{
"fullName": {
"caseInsensitiveContains": "carlos"
}
},
{
"email": {
"caseInsensitiveContains": "example"
}
}
]
}
}

Response

{
"data": {
"searchCustomers": {
"edges": [
{
"node": {
"id": "c_XXXXXXXXXXXXXXXXXXXXXXXXXX",
"externalId": "cus_98f1",
"shortName": "Carlos",
"fullName": "Carlos Pérez",
"email": {
"email": "c.perez@example.com"
}
}
},
{
"node": {
"id": "c_YYYYYYYYYYYYYYYYYYYYYYYYYY",
"externalId": "cus_2",
"shortName": "Carl",
"fullName": "Carl Smith",
"email": {
"email": "carl.s@company.org"
}
}
}
]
}
}
}

Searching for customers whose name contains characters with punctuation

Even if the customer's name contains characters with punctuation, our search API will return the expected results.

Variables

{
"searchQuery": {
"or": [
{
"fullName": {
"caseInsensitiveContains": "perez"
}
}
]
}
}

Response

{
"data": {
"searchCustomers": {
"edges": [
{
"node": {
"id": "c_XXXXXXXXXXXXXXXXXXXXXXXXXX",
"externalId": "cus_98f1",
"shortName": "Carlos",
"fullName": "Carlos Pérez",
"email": {
"email": "c.perez@example.com"
}
}
}
]
}
}
}