# Search for a customer

Use this workflow to search for a Customer using free text.

This is typically used when an external system does not have the customer GUID, national identity number, or organization number, but has another value that may identify the customer.

## Endpoint

```http
POST /v1/cm/search/customer
```

## When to use

Use this workflow when an external system needs to search for a customer using a flexible search value.

Typical use cases include:

- searching for a customer by email address
- searching for a customer by external identifier
- searching for a customer by customer-related text
- finding a customer when only partial information is available
- matching customer data from a CRM, ERP, self-service solution, or partner system

## Request structure

The request contains a `RequestId`, a `QueryString`, and search options.

```json
{
  "RequestId": "c0d0fc69-2da0-4d17-9c8d-5191a11d42b0",
  "QueryString": "a@b.cc",
  "ExactMatch": true,
  "SearchInternally": true,
  "SearchInCRM": false,
  "SearchInBrReg": false,
  "SearchPhoneRegistries": false
}
```

## Request fields

| Field | Description |
|---|---|
| `RequestId` | Unique request id. Use a new GUID for each request. |
| `QueryString` | Search text. This can be an email address, identifier value, or other customer-related search value. |
| `ExactMatch` | Indicates whether the search should require an exact match. |
| `SearchInternally` | Indicates whether UtilityCloud should search internally. |
| `SearchInCRM` | Indicates whether the configured CRM should be included in the search. |
| `SearchInBrReg` | Indicates whether Brønnøysund Register Centre lookup should be included in the search. |
| `SearchPhoneRegistries` | Indicates whether phone registries should be included in the search. |

## Example request

```json
{
  "RequestId": "c0d0fc69-2da0-4d17-9c8d-5191a11d42b0",
  "QueryString": "a@b.cc",
  "ExactMatch": true,
  "SearchInternally": true,
  "SearchInCRM": false,
  "SearchInBrReg": false,
  "SearchPhoneRegistries": false
}
```

## Response

The response contains a `Results` array with matching customers and accounts.

```json
{
  "Results": [
    {
      "Matchtype": "Internal",
      "Guid": "b5bb1a38-8159-3ebe-b4ae-6c73e957e66e",
      "Customer": {},
      "Account": {}
    }
  ]
}
```

## Response fields

| Field | Description |
|---|---|
| `Results` | List of matching search results. |
| `Matchtype` | Indicates where the match was found, for example internally in UtilityCloud. |
| `Guid` | UtilityCloud GUID for the matching customer. |
| `Customer` | Customer object for the matching result. |
| `Account` | Account object related to the matching result. |

## Notes

This is a free text search and may also search historical data.

Always verify the returned result before using it in a business process such as contract creation, customer update, or synchronization.

Use `ExactMatch: true` when the search value should match exactly, for example when searching by email address or external identifier.

Use `SearchInternally: true` when searching customer data stored in UtilityCloud.

External searches such as CRM, Brønnøysund Register Centre, or phone registries depend on tenant configuration and available integrations.

## Related endpoints

```http
POST /v1/cm/search/customer
POST /v1/cm/customers/search
POST /v1/cm/customers/phone
GET /v1/cm/customer/{guid}
POST /v1/cm/contracts
```