Feature Search

Feature Search

Data that Enneo passes to your code (Input)

{
  "customerId": "C-abcd-123",
  "contractId": "123",
  "my-custom-parameter": "abcd", // to be configured in enneo settings
  "any-other-parameter-the-ai-found": "abcd",
  "ticketId": 123, // always provided natively by enneo, regardless of AI search results
}

The variable names, e.g. customerId or my-custom-parameter, can be defined by the user under settings -> customer and contract search -> customer identification using AI -> Search parameters for customer identification, including the prompt used for recognition. The above values are examples.

Data structure expected by Enneo as a return value (Output)

{
  "contractId": "100001", // contract id of the found contract. cannot be null
  "customerId": "200001", // customer id associated to the found contract. cannot be null
}

Notes:

• Enneo always expects exactly one or no contract. If the search parameters deliver more than one result, the search must be narrowed down to exactly one result before calling Enneo.
• If the search does not deliver any results, Enneo expects an empty object ({}) or a null result (null).
• If user wants to override Enneo authentication, the customerLegitimation and customerLegitimationMessage properties can be included. More information can be found on the relevant documentation page ([/de/system-integration/customer-recognition/contract-legitimation]).

Show Legacy data format

Enneo also supports the legacy data format, which is structured like this:

[
  {
    "id":"100001",
    "contract":{
       "customerId":"200001"
    }
  }
]

While this format is deprecated, it is (for now) supported with no removal date scheduled.

Sample implementation

PHP

<?php

// Load enneo SDK. Input is made available through $in
use EnneoSDK\ApiEnneo;
use EnneoSDK\Setting;
use EnneoSDK\Api;
require(getenv()['SDK']);

// The AI can detect these variables if provided by the customer in his request
// If you leave the default setting unchanged, $in contains:
// $in->contractId, $in->customerId, $in->firstname, $in->lastname, $in->phone, $in->company, $in->email, $in->meterNumber, $in->address, $in->postalCode, $in->city
// However, feel free to change them, and the detection prompt, according to your needs. Head over to the setting at "Customer and contract search" -> "Search Parameters Customer Identification"

// Get additional metadata from the ticket that might be needed, e.g. channel-dependent authorization
// Note that customer identification and thus this code is one of the first steps in ticket processing, so tags, AI agents, sentiment etc.,  are not (yet) available and will therefore not be included in the ticket API call
try {
//$ticket = ApiEnneo::get('/api/mind/ticket/'.$in->ticketId);
} catch (Exception $e) {}

// Preprocessing can also be done, e.g. input manipulation operations, as in this example
if (isset($in->contractId) && ($in->contractId == 7155559 || $in->contractId == 71559)) {
$in->contractId = 715559;
}

// Do we have a contract id? Then let's do a direct contract search
if ($in->contractId ?? false) {
// Search for the contract id
try {
    $contract = ApiEnneo::get('/api/mind/contract/'.$in->contractId);
} catch (Exception $e) {$contract = null;}
if ($contract?->id) {
    echo json_encode(['contractId' => $contract->id, 'customerId' => $contract->customerId]);
    exit;
}
}

// Do we have a customer id? Then let's do a direct customer search and return the first contract
if ($in->customerId ?? false) {
try {
    $customer = ApiEnneo::get('/api/mind/customer/byCustomerId/'.$in->customerId);
} catch (Exception $e) {$customer = null;}
if ($customer?->id) {
    foreach ($customer->contractIds as $contractId) {
        echo json_encode(['contractId' => $contractId, 'customerId' => $customer->id]);
        exit;
    }
}
}

// Perhaps the LLM detected a customer ID as contract ID and vice versa. Let's try
if ($in->contractId ?? false) {  // In case the LLM found a contract ID that is actually a customer ID
try {
    $customer = ApiEnneo::get('/api/mind/customer/byCustomerId/'.$in->contractId);
} catch (Exception $e) {$customer = null;}
if ($customer?->id) {
    foreach ($customer->contractIds as $contractId) {
        echo json_encode(['contractId' => $contractId, 'customerId' => $customer->id]);
        exit;
    }
}
}
if ($in->customerId ?? false) { // In case the LLM found a customer ID that is actually a contract ID
try {
    $contract = ApiEnneo::get('/api/mind/contract/'.$in->customerId);
} catch (Exception $e) {$contract = null;}
if ($contract?->id) {
    echo json_encode(['contractId' => $contract->id, 'customerId' => $contract->customerId]);
    exit;
}
}


// Otherwise, let's pass the remaining search terms to a user-defined API
// Add your handling code here that finds the customers based on the input data
$contractRawData = Api::call(method: 'GET', url: 'https://admin.enneo.ai/api/seed-contracts/search?' . http_build_query($in));
if ($contractRawData) {
$results = [
    'contractId' => $contractRawData[0]->id, // e.g. "123". Mandatory to be provided
    'customerId' => $contractRawData[0]->customerId, // e.g. "C-456789". Mandatory, but requirement will be removed in a future enneo version
];
} else {
$results = [];
}

// Note: You may choose to override the default enneo legitimation. In this case, you can set these variables. Further details are available at https://docs.enneo.ai/de/system-integration/customer-recognition/contract-legitimation
//$searchResults[0]['customerLegitimation'] = 10; // Either 0, 10, 20 or 30, see the docs for further information
//$searchResults[0]['customerLegitimationMessage'] = "Customer did not provide his special code";   

// Finally, return the matching contracts in this data structure
echo json_encode($results);