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​

The searchCustomers query is available to search for customers.

This query supports pagination and returns a CustomerSearchConnection object.

In order to search, the searchQuery parameter needs to be provided in searchCustomers, which consists of a group of search conditions.

Up to 15 different search conditions can be provided. Each CustomerSearchCondition) consists of:

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

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 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​

Any combination of search conditions can be used (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, the 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"
            }
          }
        }
      ]
    }
  }
}

If you have any problems, please get in touch with us by email on help@plain.com, and we will be happy to help.