API Customer groups

Api/Customersgroup allows to manage customers.

Your API user needs access to Customers module. from settings/roles, you can modify permissions for role assigned to your API user. Sometimes, permission allow seeing all customers is needed.

This article covers all possible commands for customer API.

Available commands:

Api/Customers/getFields - needed for building customer data for save
Api/Customers/get ([id],[externalId], [filters]) - asks data of one or more customers
Api/Customers/getIdsByFieldValues (conditions) - filters customers using sophisticated search, and gets back list of customer ID-s
Api/Customers/geocode (id | externalId) - geocodes a customer
Api/Customers/save (id | externalId, location, fields) - creates new customer, or modifies data for existing customer
Api/Customers/delete (id | externalId) - deletes one customer
Api/Customers/deleteByIds (ids) - delete multiple customers by ID-s
Api/Customers/applyDisplayRules - reapplies display rules

getFields

Asks for customer fields. They are needed later when composing call for adding or editing existing customer.

No extra permissions are needed.

Syntax

Api/Customers/getFields

Response

Inside <response/> element, there is list of <fields/> elements, what contains following elements:

id - unique field number in database
name - human-readable field name, may be localised for language used by API user
type - field type, expand list below to see details.

Field types

text - may contain free text
number - field contains a number
id - field contains unique customer identificator, in sense of other API commands, value for externalId
name - customer name. This field has strong semantic meaning for customers
combo - field contains array of values, where you can choose from
date - field contains date in format YYYY-mm-dd
html - fields contains HTML webpage
address-1 .. address-7 - field contains parts of customer addresses. If more than 1 fields are used, all of them are combined when geocoding customer location
latitude - field contains latitude part of world coordinates
longitude - field contains longitude part of world coordinates
m_style - marker style of customer, used for styling customer on map. Possible values: circle, star, diamond, cross, dcross (diagnonal cross), square, triangle
phone - contains phone number
link - contains web link
email - contains e-mail address
personid - field contains list of person unique numbers, and matches to type persons in FleetComplete.

Following values are part of target visits feature:

visitCount - how much customer manager must visit customer in certain times period
visitGroup - into what department this customer belongs to
visitDrive - who manages that customer

Example

<?xml version="1.0" encoding="utf-8" ?>
<nodes>
  <status>0</status>
  <meta>
  </meta>
  <response>
    <fields>
      <field>
        <id>35467</id>
        <type>id</type>
        <name>id</name>
      </field>
      <field>
        <id>33096</id>
        <type>name</type>
        <name>name</name>
      </field>
      <field>
        <id>33097</id>
        <type>address-1</type>
        <name>address</name>
      </field>
      <field>
        <id>33098</id>
        <type>phone</type>
        <name>phone</name>
      </field>
      <field>
        <id>33099</id>
        <type>link</type>
        <name>website</name>
      </field>
    </fields>
  </response>
</nodes>

get

Asks for one or more customers.

If API user does not have permission allow seeing all customers, then only those customers are output, where it is assigned as manager (via persons in FleetComplete field).

Syntax

Api/Customers/get ([id], [externalId], [filters])

All parameters are optional.

id: give data for one customer, specified by unique database ID. Same identificator is in response, <id/> field.
externalId: find customer by its unique external ID
filters: JSON array, what contains additional key:value value for filtering out customers. Field ID-s must be strings, like every properly formatted JSON.
for string types, field must contain that text
for other types, match must be 1:1
AND logic between fields, fields must match to all given conditions

Note that in response, <customers/> element is empty, when:

there is no customer with such id or externalId
if both id and externalId are given, they must be equal on same customer
id is non-numeric

Response

<response/> contains element <customers/>, what has list of <customer/> inside it. Each customer contains following details:

id: unique database number, useful for other API commands
externalId: if used, user-defined identificator, what ideally should be unique
fields: contains individual <field/> elements , what contains:
id: database identificator
name: human-readable name
value: field value of customer
location: geocoded customer location information , some of them filled via geocoding:
latitude, longitude
rawAddress: this address was used for geocoding
postalCode
country
estate
municipality
settlement
importedAddress
normalizedAddress
insertTimestamp: when customer was created
lastUpdateTimestamp: last time when customer was modified

Examples

Ask for all customers:

Api/Customers/get

Ask one customer via externalId:

Api/Customers/get?externalId=partner

Use filter:

Api/Customers/get?filter={"35467":"Partner"}

Possible response:

<?xml version="1.0" encoding="utf-8" ?>
<nodes>
  <status>0</status>
  <meta>
  </meta>
  <response>
    <customers>
      <customer>
        <id>10120578</id>
        <externalId>partner</externalId>
        <fields>
          <field>
            <id>35467</id>
            <name>id</name>
            <value>partner</value>
          </field>
          <field>
            <id>33096</id>
            <name>name</name>
            <value>Partner LLC</value>
          </field>
          <field>
            <id>33097</id>
            <name>address</name>
            <value>Allika 14, Roela</value>
          </field>
          <field>
            <id>33098</id>
            <name>phone</name>
            <value>+37255555555</value>
          </field>
          <field>
            <id>33099</id>
            <name>website</name>
            <value>www.partner.ee</value>
          </field>
        </fields>
        <location>
          <latitude>59.165831907682</latitude>
          <longitude>26.595877398979</longitude>
          <rawAddress>
          </rawAddress>
          <postalCode>46602</postalCode>
          <country>Estonia</country>
          <county>Lääne-Viru County</county>
          <estate>Allika 14</estate>
          <municipality>Vinni Parish</municipality>
          <settlement>
          </settlement>
          <importedAddress>
          </importedAddress>
          <normalizedAddress>Allika 14, Roela, 46602 Lääne-Viru maakond, Estonia</normalizedAddress>
          <lastGeocodeTimestamp>2025-07-25 12:42:01+0300</lastGeocodeTimestamp>
        </location>
        <insertTimestamp>2019-10-25 14:16:10+0300</insertTimestamp>
        <lastUpdateTimestamp>2025-07-25 11:56:16+0300</lastUpdateTimestamp>
      </customer>
    </customers>
  </response>
</nodes>

getIdsByFieldValues

Allows to create fine-tuned search queries over customers. Outputs only customer ID-s.

Requirements

external id on customers You need to assign externalId-s to fields via settings - customers, because search conditions are made by those. Currently, they are not accessible via getFields command.

Syntax

Api/Customers/(conditions)

conditions is array of JSON key-value object with following fields:

fieldId: externalId of customer fields
operator: logic operand [not] like, eq, lt[e], gt[e], ne. Possible values:
like - field contains that text or pattern, if value also contains wildcards %
not like - field does not match to given pattern (opposite to like)
eq, = - equal with value
lt, < - less than value
lte, <= - less or equal than value
gt, > - greater than value
gte, >= - greater or equal than value
ne, <> - not equal with value
value: search value, what may contain % as wildcard, what represents any set of one or more characters

Response

If successful, inside <response/> element, there is <customerIds/> with individual <customerId/> elements with ID values of customers.

Examples

Ask for LLC customers, what end with r:

Api/Customers/getIdsByFieldValues?conditions=[{"fieldId":"nameid","operator":"like","value":"%r LLC"}]

Multiple conditions:

Api/Customers/getIdsByFieldValues?conditions=[{"fieldId":"nameid","operator":"like","value":"%r LLC"},
{"fieldId":"phoneid","condition":"not like","value":"5%"}]

Possible response:

<?xml version="1.0" encoding="utf-8" ?>
<nodes>
  <status>0</status>
  <meta>
  </meta>
  <response>
    <customerIds>
      <customerId>17813121</customerId>
      <customerId>10120578</customerId>
    </customerIds>
  </response>
</nodes>

save

Creates new customer or changes existing one

Requirements

You need permission allow editing of customers, what can be assigned to settings - roles.

Syntax

Api/Customers/save ([id | externalId], location, fields)

id: unique customer ID. Use it if you want to change values on existing customer
externalId: user-defined, preferrably unique identificator
location: JSON array with name, latitude, longitude, or rawaddress
name: customer name
latitude, longitude: customer location
rawaddress: customer postal address. If coordinates are not given, then it should be detailed enough to find geocoded position
fields: other customer values in JSON format, key-value array, where keys are taken from getFields id-elements

This is how id and externalId works in combination:


`id` ↓ / `externalId` →	missing	filled
missing	create new customer	try to find customer by `externalId` and update it, or create new if not found
filled	update customer with given `id`	update customer with given `id`, and change its `externalid`

Location

every customer should have geocoded location, and this variable sets essential customer properties like name and address.

name sets customer name, and additionally, value for column, where system type is name

Customer location can be set either via rawaddressor world coordinates set by latitude and longitude.

If address is given, location is tried to get via geocoding

if coordinatesare given, customer address is searched via reverse geocoding.

Here's example of such JSON:

{
 "name":"White House",
 "rawaddress":"1600 Pennsylvania Avenue, NW, Washington, USA",
 "latitude":"38.8978",
 "longitude":"-77.0365"
}

Fields

getfields gives list of ID-s with field name and type You need to use ID and value for fields parameter. You may skip parameters, what set customer name or address details, because they are already included in location parameter.

Given getfields example above, we have following columns:


id	35467	33096	33097	33098	33099
type	id	name	address-1	phone	link
name	id	name	address	phone	website
exists elsewhere?	externalid	location:name	location:address

as you can see, there is no point to include id, name, and address fields here, so, fields parameter looks like:

fields={
  "33098":"+12024567041",
  "33099":"https://www.whitehouse.gov/"
}

Examples

Simplest way to create one customer is to simply use location parameter. Additionally, if you don't have unique externalId-s, you can skip this parameter also:

Api/Customers/save?
  externalId=whitehouse&
  location={"name":"White House","rawaddress":"1600 Pennsylvania Avenue, NW, Washington, USA"}

With fields:

Api/Customers/save?
 externalId=whitehouse&
 location={"name":"White House","rawaddress":"1600 Pennsylvania Avenue, NW, Washington, USA"}&
 fields={"33098":"+12024567041",
 "33099":"https://www.whitehouse.gov/"}

Changing anything on existing customer, like address:

Api/Customers/Save?
  externalId=whitehouse&
  location={"rawaddress":"Kungla tn 4a-11, 10411 Tallinn, Eesti"}

delete

Deletes existing customer

Requirements

API user needs permission to edit customers.

Syntax

Api/Customers/delete (id | externalId)

id: unique number of customer
externalId: user-defined value of customer

If both are provided, this externalId must exist on that customer with that id.

Examples

Delete with ID:

Api/Customers/delete?id=1234

Delete with externalId:

Api/Customers/delete?externalId=whitehouse

deleteByIds

Deletes multiple customers

Requirements

API user needs permission to edit customers.

Syntax

Api/Customers/deleteByIds (ids)

ids: array of numbers in JSON format, or list inside brackets []

Example

Api/Customers/deleteByIds?ids=[9316727,8415962]

API Customer groups

Related Articles

Api/Customersgroup allows to manage customers.

getFields

Syntax

Response

Field types

Example

get

Syntax

Response

Examples

getIdsByFieldValues

Requirements

Syntax

Response

Examples

save

Requirements

Syntax

Location

Fields

Examples

delete

Requirements

Syntax

Examples

deleteByIds

Requirements

Syntax

Example