Copy page

Common workflows

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

Code
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.

Code
{
  "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

Code
{
  "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.

Code
{
  "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

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