---
title: Customer Identification
slug: devdocs/customer-identification
docTags: 
createdAt: 2026-10-16T12:03:51.970Z
---

Use `customers.customer` to find a customer. It filters by phone, code, first name, last name or public key. You can combine the filters.

:::BlockQuote
ℹ️ **INFO**
The query returns active customers by default, sorted by first name.
:::

## Find a customer by phone

**Query**

```graphql
query FindCustomers($phone: String, $code: String, $firstName: String, $lastName: String, $first: Int, $after: String) {
  customers {
    customer(phone: $phone, code: $code, firstName: $firstName, lastName: $lastName, first: $first, after: $after, orderBy: LAST_NAME) {
      totalCount
      pageInfo {
        hasNextPage
        endCursor
      }
      items {
        publicKey
        firstName
        lastName
        active
        code
        email
        mobilePhone
        category { publicKey name }
        segmentationCategory { publicKey name }
      }
    }
  }
}
```

**Variables**

```json
{
  "phone": "0700000001",
  "first": 30,
  "after": null
}
```

**cURL**

```bash
curl --location 'https://sandbox.expressoft.eu/connect/api/interopgql' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{"query": "query FindCustomers($phone: String, $code: String, $firstName: String, $lastName: String, $first: Int, $after: String) { customers { customer(phone: $phone, code: $code, firstName: $firstName, lastName: $lastName, first: $first, after: $after, orderBy: LAST_NAME) { totalCount pageInfo { hasNextPage endCursor } items { publicKey firstName lastName active code email mobilePhone category { publicKey name } segmentationCategory { publicKey name } } } } }", "variables": {"phone": "0700000001", "first": 30, "after": null}}'
```

**Response**

```json
{
  "data": {
    "customers": {
      "customer": {
        "totalCount": 1,
        "pageInfo": {
          "hasNextPage": false,
          "endCursor": "MQ=="
        },
        "items": [
          {
            "publicKey": "00000000-0000-0000-0000-000000000001",
            "firstName": "Jane",
            "lastName": "Doe",
            "active": true,
            "code": "ADD1",
            "email": "jane.doe@example.com",
            "mobilePhone": "0700000001",
            "category": {
              "publicKey": "00000000-0000-0000-0000-000000000010",
              "name": "Gold customers"
            },
            "segmentationCategory": null
          }
        ]
      }
    }
  }
}
```

Check `totalCount`. If it is `1`, take the `publicKey` of the customer: it is the identifier for the other flows. If it is `0`, no customer matches: you can create one (see **Creating a Customer**).

## Other filters

Send the filters you need in `variables`. Leave out the ones you don't use.

| Variable                | Filters by                                       |
| ----------------------- | ------------------------------------------------ |
| `phone`                 | The phone number.                                |
| `code`                  | The customer code.                               |
| `firstName`, `lastName` | The name. The filter accepts a part of the name. |

To find customers by key, use the `publicKey` argument, which takes a list: `customer(publicKey: [$key])`.

## Page through the customers

To list many customers, set `first` and send the `endCursor` of each page as `after`, until `hasNextPage` is `false`. You can sort with `orderBy`: `FIRST_NAME`, `FIRST_NAME_DESC`, `LAST_NAME`, `LAST_NAME_DESC`.

## Customer categories

Every customer has a category. You need a category key to create a customer.

**Query**

```graphql
query GetCustomerCategories {
  customers {
    customerCategories {
      publicKey
      name
    }
  }
}
```

**cURL**

```bash
curl --location 'https://sandbox.expressoft.eu/connect/api/interopgql' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{"query": "query GetCustomerCategories { customers { customerCategories { publicKey name } } }"}'
```

**Response**

```json
{
  "data": {
    "customers": {
      "customerCategories": [
        {
          "publicKey": "00000000-0000-0000-0000-000000000010",
          "name": "Gold customers"
        },
        {
          "publicKey": "00000000-0000-0000-0000-000000000011",
          "name": "Silver customers"
        }
      ]
    }
  }
}
```

:::BlockQuote
💡 **TIP**
`segmentationCategory` is `null` for customers that have no segmentation assigned.
:::