Clients

Clients are one of Custom Link’s master-data entities — lower churn than orders, but still needed for validation (e.g. resolving a ClientNumber before order intake) and for keeping an external system in sync. For the other master-data entity, see Employees.

When to use

Situation	Command
Look up client(s) by Id, number, or search text	RequestClients
Create or update a client	StoreClients

Retrieve

Retrieving clients

<?xml version="1.0" encoding="windows-1252"?>
<EoCustomLinkRequestClients Type="TEoCustomLinkRequestClients">
  <Nested>False</Nested>
  <Filter Type="TEoFilterClients">
    <Active>fsActiveOnly</Active>
    <KeysExplicitAsCsv>110,111</KeysExplicitAsCsv>
  </Filter>
</EoCustomLinkRequestClients>

Filter field	Type	Description
Active	enum	fsActiveOnly (default), fsActiveNot, or fsActiveBoth.
KeysExplicitAsCsv	string (CSV)	Internal MendriX client Ids. If you send both this and NumbersExplicitAsCsv, KeysExplicitAsCsv silently wins and NumbersExplicitAsCsv is ignored.
NumbersExplicitAsCsv	string (CSV)	External client numbers — use when your source system only knows the client number, not the internal Id.
Search	string	Free-text search on name, contact person, street, postcode, city, phone, fax, country.
Administration	int	Which MendriX administration to query. -2 = all administrations (safest default if unsure).
TrashBin	boolean	True returns only deleted clients. Usually pointless to combine with Active=fsActiveOnly, since a deleted client’s active/inactive state is typically not meaningful.
MarkChars	string	Filter by mark characters (internal categorization). Usually left empty.

Response fields (TEoClientMx)

Field	Type	Description
ClientId	key	Internal database Id.
Number	string	External client number (visible in the MendriX UI).
Address	address	Visiting address (name, street, postcode, place, country). Longitude/Latitude use the sentinel 99999.0 to mean “unknown” — don’t treat it as a real coordinate.
AddressInvoice	address	Invoice address.
AddressInvoicePerson	string	Contact person for the invoice address.
Connectivity	connectivity	Email, phone, fax, mobile, and website (Web).
ContactName	string	Default contact person.
AdministrationId	key	Which administration this client belongs to.
Deleted	boolean	True if the client is in the trash bin.
OrderEntryDisabled	boolean	True blocks new order entry for this client.
OrderEntryAlwaysMessage	string	Fixed message shown at order entry for this client, if any. Empty = no message.
InvoiceEmailAddress	string	Email address invoices are sent to.
InvoiceCollection	boolean	True if this client receives collected/batched invoices.
BankAccount	string	IBAN or bank account number.
PaymentTerm	int	Payment term in days.
TaxCode	string	One-character tax code (internal foreign key).
VatCode	string	VAT number.
CommerceNumber	string	Chamber of commerce registration number.
HandlingTime	string	Default handling time for this client, if set.
CustomLabelRefOur / CustomLabelRefYour	string	Custom labels for the “our reference”/“your reference” fields, if this client uses non-default labels.
WorldLinkUserName	string	Login username for this client’s WorldLink/customer-portal access, if configured.
DistanceCalculationType	int	How distance is calculated for this client’s orders.
DistancePercentage	decimal	Surcharge/discount percentage on calculated distance.

Empty results, not an error

When no client matches your filter, MendriX returns an empty result list, not an error — handle this case rather than treating it as a failure.

Scenarios

Scenario: validate a client number before order intake. Set NumbersExplicitAsCsv to the number your source system provided; an empty result means the number doesn’t exist in MendriX and the order should be rejected client-side before you attempt StoreOrdersNormal.

Scenario: sync all active clients into an external CRM. Omit KeysExplicitAsCsv/NumbersExplicitAsCsv/Search, leave Active=fsActiveOnly, and page through results (large tenants may return many clients — request in reasonable batches, see don’t hammer the server).

Scenario: find a client by name. Set Search to the name or partial name — matches name, contact person, address fields, and phone/fax.

Store

Creating or updating a client

Use the same retrieve-edit-resend pattern recommended for orders — see Custom Link: rules of engagement for why this is worth doing even though it isn’t enforced for clients. A ClientId/Id that is zero or negative creates a new client; positive updates the existing one.

Fields: see the field table under the Retrieve tab above — the same TEoClientMx shape is used for both directions.

Response uses the shared EoStoreResultList shape.

Scenarios

Scenario: create a new client. Send StoreClients with ClientId/Id set to zero or a negative value and the required address/contact fields — the response’s EoStoreResult returns the new positive Id.

Scenario: update a client’s invoice email. Retrieve the client via RequestClients, change only InvoiceEmailAddress in the returned XML, and resend the full client record with its existing positive Id.

Gotchas

• A Custom Link token’s access to Clients is all-or-nothing — if the token’s section is denied (DenyAll), every RequestClients/ StoreClients call fails with a Security: no permission for request <ClassName> error. This is different from Orders/Invoices tokens, which support a LimitToClientId mechanism that silently narrows results to one client instead of rejecting the request — Clients tokens have no such mechanism. Administration-level scoping (which administrations a token can see) still applies independently and can narrow results without an error.
• StoreClients is not rejected for skipping a prior retrieve — the server updates the DB row directly. This differs from orders; see Custom Link: rules of engagement. There is a real asymmetry worth knowing about, though: for clients, the server still fetches the existing row itself before storing, so a partial payload against an existing client merges rather than blanking other fields — unlike employees, where no such server-side fetch happens.
• KeysExplicitAsCsv vs. NumbersExplicitAsCsv — these filter on different keys (internal Id vs. external number). Use the one that matches the identifier your source system provides; if you send both, KeysExplicitAsCsv silently wins and NumbersExplicitAsCsv is ignored.

Related commands

• Employees — the other master-data entity.
• Order intake — orders reference clients via ClientNumber/ClientId.
• GdxEoStructures.xsd — TEoClientMx field definitions.