Copy page

Common workflows

Find customer by identification

Use this workflow to find a Customer by national identity number or organization number.

This is typically used before creating a Contract, synchronizing customer data, or deciding whether a customer already exists in UtilityCloud.

Endpoint

Code
POST /v1/cm/customers/search

When to use

Use this workflow when an external system needs to find a customer based on a known identification value.

Typical use cases include:

• checking whether a private customer already exists before creating a Contract
• checking whether a business customer already exists before creating a Contract
• looking up the UtilityCloud customer GUID from a CRM, ERP, self-service solution, or partner system
• validating customer existence before updating customer-related data

Request structure

The request contains a Customers array with one or more identification values.

Code
{
  "Customers": [
    "<identification>"
  ]
}

The identification value is typically:

Customer type	Identification
Private customer	National identity number
Business customer	Organization number

Example request

Code
{
  "Customers": [
    "31074355544"
  ]
}

Response

The response contains a Customers array with the identification value and the matching UtilityCloud customer GUID.

Code
{
  "Customers": [
    {
      "Identification": "31074355544",
      "Guid": "9c571be0-a689-4b83-9343-4043b5328836"
    }
  ]
}

Response fields

Field	Description
Identification	The identification value used in the search request.
Guid	The UtilityCloud GUID of the matching Customer.

If no matching customer is found, Guid may be returned as null.

Notes

Use the returned Guid when calling endpoints that require the UtilityCloud customer identifier.

The endpoint can be used to search for both private customers and business customers.

For private customers, the identification value is normally a national identity number.

For business customers, the identification value is normally an organization number.

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

Related endpoints

Code
POST /v1/cm/customers/search
POST /v1/cm/customers/phone
POST /v1/cm/search/customer
POST /v1/cm/contracts