pixiCustomerKeyByEmail

Looks up a customer by e-mail address within one shop and returns its internal key as a single integer value.

A customer matches if @eMail equals either the eMail or the eMail2 field and the customer belongs to the shop @ShopId (CustomerOf).
Only customers that have at least one address record (Addresses.AdrCustRef = CustKey) can be returned, because the lookup uses an inner join on the addresses.
With @AllowAmbiguous = 0 (default) a key is returned only if exactly one customer in the shop has this e-mail address. If several customers share the address, the result is NULL.
With @AllowAmbiguous = 1 the uniqueness check is skipped and the key of one of the matching customers is returned.
If no customer matches, the result is NULL.

Notes

All reads use NOLOCK, so uncommitted data may be seen.
When @AllowAmbiguous = 1 and several customers match, the choice is made with TOP 1 without ORDER BY; which customer is returned is not deterministic.
The uniqueness count only considers the Customers table, not the address join. A single matching customer without any address therefore yields NULL.
NULL is returned both for "not found" and for "ambiguous"; the caller cannot distinguish these cases from the result alone. Call again with AllowAmbiguous = 1 to check whether matches exist.
Whether the comparison is case-sensitive depends on the database collation; no trimming or normalisation of the e-mail address is done.

Tables used

Customers · Read Addresses · Read

Parameter Type Default Description

Parameter	Type	Default	Description
`eMail` Required	varchar(60) string	–	E-mail address to search for; compared with the customer's `eMail` and `eMail2` fields. Example: `max.mustermann@example.com`
`ShopId` Required	char(3) string	–	Shop ID the customer must belong to (`CustomerOf`). Example: `SHP`
`AllowAmbiguous`	bit boolean	0	Controls whether a key is returned when several customers of the shop share the e-mail address. Allowed values `0` – Return a key only if exactly one customer in the shop matches; otherwise `NULL`. `1` – Return the key of any one matching customer, even if several match. Example: `0`

eMail

Required

varchar(60)
string

–

E-mail address to search for; compared with the customer's eMail and eMail2 fields.

Example: max.mustermann@example.com

ShopId

Required

char(3)
string

–

Shop ID the customer must belong to (CustomerOf).

Example: SHP

AllowAmbiguous

bit
boolean

0

Controls whether a key is returned when several customers of the shop share the e-mail address.

Allowed values

0 – Return a key only if exactly one customer in the shop matches; otherwise `NULL`.
1 – Return the key of any one matching customer, even if several match.

Example: 0

Result set 1 · Always (single scalar value; `NULL` if no unique match is found)

Return value of the scalar function: the customer key.

Column	Type	Description
`Result` Nullable	int	`CustKey` of the matching customer, or `NULL` if no customer matches or (with `AllowAmbiguous = 0`) the address is not unique in the shop.

Response example

<SqlRowSet1>
  <row>
    <Result>10452</Result>
  </row>
</SqlRowSet1>

POST https://apigateway.descartes.com/tms/pixi/
Content-Type: text/xml; charset=utf-8
Authorization: Basic BASE64(USERNAME:PASSWORD)

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="https://apigateway.descartes.com/tms/pixi/">
  <SOAP-ENV:Body>
    <ns1:pixiCustomerKeyByEmail>
      <eMail>max.mustermann@example.com</eMail>
      <ShopId>SHP</ShopId>
      <!-- <AllowAmbiguous>0</AllowAmbiguous> -->
    </ns1:pixiCustomerKeyByEmail>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

curl -X POST 'https://apigateway.descartes.com/tms/pixi/' \
  --user 'USERNAME:PASSWORD' \
  --header 'Content-Type: text/xml; charset=utf-8' \
  --data-binary @- <<'XML'
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="https://apigateway.descartes.com/tms/pixi/">
  <SOAP-ENV:Body>
    <ns1:pixiCustomerKeyByEmail>
      <eMail>max.mustermann@example.com</eMail>
      <ShopId>SHP</ShopId>
      <!-- <AllowAmbiguous>0</AllowAmbiguous> -->
    </ns1:pixiCustomerKeyByEmail>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
XML

<?php

$soapClient = new SoapClient(null, [
    'login' => 'USERNAME',
    'password' => 'PASSWORD',
    'location' => 'https://apigateway.descartes.com/tms/pixi/',
    'uri' => 'https://apigateway.descartes.com/tms/pixi/',
]);

$arguments = [
    'eMail' => 'max.mustermann@example.com',
    'ShopId' => 'SHP',
    // 'AllowAmbiguous' => '0',
];

$soapArguments = [];
foreach ($arguments as $name => $value) {
    $soapArguments[] = new SoapVar($value, XSD_STRING, '', '', $name);
}

$response = $soapClient->__soapCall('pixiCustomerKeyByEmail', $soapArguments);

Notes

Tables used

Result set 1 · Always (single scalar value; NULL if no unique match is found)

Response example

Result set 1 · Always (single scalar value; `NULL` if no unique match is found)