getCustomers

Retrieve your customer database.

In addition to customer card fields, you can have API to return:

  • customer addresses (set getAddresses = 1);
  • customer contact persons (set getContactPersons = 1);
  • customer balance (set getBalanceInfo = 1)
To add or edit a customer record, use saveCustomer.

Each customer belongs to a customer group (see getCustomerGroups).

To retrieve current reward points balance for a particular customer, see getCustomerRewardPoints.

Important: if you operate in the European Union, the General Data Protection Regulation (GDPR) requires all processing done with customers' personal information to be logged. Every time you retrieve customer information with the getCustomers call, you are responsible for logging everything you do with the data. If it is not possible to keep the logs in the system that processes the data, you may consider writing the log entries into Erply, with the logProcessingOfCustomerData call.

Input parameters

Parameter name Description Possible value Required
customerID Customer's ID Integer
customerIDs List of customer ID's, separated by commas, eg. "1,2,3,4,5". (Do not put spaces around commas.) String
searchFromMiddle If set to 1, and you have supplied input parameters "seachName" or "searchPersonFullName", API will search from anywhere within the field, not just the beginning. 0 or 1
searchName Search by customer name, e-mail, phone, cellphone or customer card #. Partial matches are also returned, but InventoryAPI searches only from the beginning of each field. Set searchFromMiddle = 1 to search from anywhere within the field. String
searchNameIncrementally A more optimized customer search. It is meant for cases where API should return quickly the most relevant results, but the search does not have to be exhaustive.

When using searchNameIncrementally, the results are not ordered and you cannot use paging (pageNo), nor specify how many results you want to retrieve. Pay no attention to the "recordsTotal" field - it returns a random large number!

"searchNameIncrementally" also searches from company registry code / National ID (exact matches only), while input parameter "searchName" does not.
String
searchPersonFullName Search by person full name - first name, space and last name, eg. "John Smith". Partial matches are also returned, but InventoryAPI onlt searches from the beginning of the field. Set searchFromMiddle = 1 to search from anywhere within the field. String
searchPersonFirstName Search by person first name. Exact matches only. String
searchPersonLastName Search by person last name. Exact matches only. String
searchEmail Search by email address. Exact matches only. String
searchMobile Search by mobile number. Exact matches only (including spaces). String
searchVATNo Search by customer VAT no (field vatNumber). Exact matches only. String
searchCode Search by customer card # (field customerCardNumber). Exact matches only. String
searchRegistryCode Search by company registry code or person's national ID (field "code"). Exact matches only. String
searchAttributeName Name of attribute to search from. Both "searchAttributeName" and "searchAttributeValue" have to be specified. Error 1030 will be returned if value is an array. String
searchAttributeValue Attribute value to search for. Error 1030 will be returned if value is an array. String
clientManagerID Customer manager. (See getEmployees.) Integer
groupID Retrieve customers in this specific customer group. (See getCustomerGroups.) Integer
groupIDWithSubgroups Retrieve customers in this specific customer group, or in any of its sub-groups, sub-sub-groups etc (if you have a multi-level tree of customer groups). Integer
payerID Payer ID. Integer
GLN GLN. String
taxOfficeID Filter customers by tax office ID.

This is a Greece-specific field and this filter can only be used on Greek accounts. On other accounts, API will return error code 1128.
Integer
flagStatus Whether the customer is marked with an importance flag or not. 0 or 1
doNotSell Whether the customer is marked with a do not sell flag or not. 0 or 1
colorStatus Optional colored flag associated with this customer. Possible values: "", "red", "green", "yellow", "blue". String
mode CUSTOMERS, CONTACTS or ALL.
By default CUSTOMERS.

Erply makes a distiction between 1) companies and persons who are customers in their own right, and 2) persons who are marked as contact persons of some other customer. Option "CUSTOMERS" returns only the first ones, "CONTACTS" returns only the second ones and "ALL" returns both.
String
getBalanceInfo If set to 1, API also returns balance info for selected customers.

If you need to retrieve balances only, without customer information, take a look at API call getCustomerBalances.
Integer (0 or 1)
getBalanceWithoutPrepayments Integer (0 or 1)
getPOSDefaultCustomers If set to 1, API returns all default customers used for POS transactions Integer (0 or 1)
getAddresses Set to 1 to retrieve all addresses for selected customers. API will return the list in element "addresses", see below.

If you need to retrieve addresses only, without customer information, take a look at API call getAddresses.
Integer (0 or 1)
getContactPersons Set to 1 to retreive contact persons for selected customers. API will return the list in element "contactPersons", see below. Integer (0 or 1)
getAssociationsAndProfessionals

Set to 1 to retrieve relationships for selected customers.

A customer can have zero or more "associations" and zero or more "professionals" linked to them, and each one of those "associations" and professionals" is a customer in itself. One of the "associations" can be a "default association", and one of the "professionals" can be a "default professional".

To add a new link (relationship), ie. to specify that Customer X is an "association" for Customer Y, see the API calls saveCustomerAssociation, saveCustomerProfessional, deleteCustomerAssociation and deleteCustomerProfessional.

Integer (0 or 1)
doNotCalculateRecordsTotal If set to 1, API will not report an accurate total number of search results (the recordsTotal field will return some constant large number). This can be used to make queries more efficient. When using doNotCalculateRecordsTotal, just ask for paged results until API will no longer return any (that indicates you hve reached the end of dataset). Integer (0 or 1)
birthdayMonthDayFrom

Filter customers by birthday — get all customers whose birthday is on or after the specified month and day.

If you only specify birthdayMonthDayFrom and not birthdayMonthDayTo, all birthdays between the specified day and the end of the year are returned.

Combine the two filters to get birthdays in a specific range (eg. birthdays in June or July). Year wrap-around is supported: filter birthdayMonthDayFrom = "12-01", birthdayMonthDayTo = "01-31" returns birthdays in December and January.

Both month and day must be two digits. Use a leading zero if necessary.

String (mm-dd)
birthdayMonthDayTo

Filter customers by birthday — get all customers whose birthday is on or before the specified month and day.

If you only specify birthdayMonthDayTo and not birthdayMonthDayFrom, all birthdays between the beginning of the year and the specified day are returned.

Combine the two filters to get birthdays in a specific range (eg. birthdays in June or July). Year wrap-around is supported: filter birthdayMonthDayFrom = "12-01", birthdayMonthDayTo = "01-31" returns birthdays in December and January.

Both month and day must be two digits. Use a leading zero if necessary.

String (mm-dd)
createdUnixTimeFrom Get all new items that have been added since a specific point in time. Integer (Unix timestamp)
createdUnixTimeTo Get all new items that have been added before a specific point in time. Integer (Unix timestamp)
externalID Get customer by specific external integration ID and name, requires integrationName. String
integrationName Get customer by specific external integration ID and name, requires externalID. String
eInvoiceReference Customer reference for e-invoices. String
homeStoreID Home store ID. Integer
signUpStoreID Sign up store ID Integer
changedSince Retrieve only items that have been added or modified since the specified timestamp. Use it to keep a local database in sync with Erply. Integer (Unix timestamp)
lang Retrieve item names in a specific language. If omitted, API will return item names in the default language of your Erply account.
Possible values:
  • 'eng' - English
  • 'spa' - Spanish
  • 'ger' - German
  • 'swe' - Swedish
  • 'fin' - Finnish
  • 'rus' - Russian
  • 'est' - Estonian
  • 'lat' - Latvian
  • 'lit' - Lithuanian
  • 'gre' - Greek
String
orderBy 'name', 'customerID', 'group', 'colorStatus', 'lastChanged', 'homeStoreID', 'signUpStoreID' or 'none' (no ordering). By default 'name'.
orderByDir Sort direction: 'asc' (ascending order) or 'desc' (descending order). By default, items are sorted in ascending order. String
recordsOnPage Number of records API should return. By default 20, at most 100. Integer
pageNo API returns at most recordsOnPage items at a time. To retrieve the next recordsOnPage items, send a new request with pageNo incremented by one. By default, API returns "page 1". Integer
getFields Comma separated list of fields. Can be used to limit the top level fields that are returned (nested fields are not filtered). When omitted then everything will be returned.

NOTE: When using this filter with a result that does not have the set field then an empty result will be returned.
String

Response

Field name Type Description
customerID Integer (deprecated alternative name: id)
customerType String COMPANY or PERSON.

  • For companies, the following attributes are set: fullName, companyName (both have the same value).
  • For persons, the following attributes are set: fullName, firstName, lastName. fullName is a combination of latter two: "lastName, firstName".

fullName can be used for displaying customer's name wherever needed.

Guidelines for applications with a customer edit form:
  • Companies should have one name field and the attribute that is edited should be companyName.
  • Persons should have separate fields for given name and surname (respective attributes: firstName, lastName).

Note: API call saveCustomer also has an input parameter "fullName" (when using that, system tries to interpret and split the name as required), but it should be used only when brokering data from some other system where a better data format is not available.
fullName String Full name of the customer, use for displaying customer name.
companyName String For companies only.
companyTypeID Integer Company type ID, for companies only.
firstName String (Given name.) For persons only.
lastName String (Surname.) For persons only.
personTitleID Integer Person title ID.
eInvoiceEmail String Email address for e-invoices. If this is empty, then the regular email address is used.
eInvoiceReference String Customer reference for e-invoices.
emailEnabled Integer Indicates whether the customer would like to get invoices on their email (0 or 1).
eInvoiceEnabled Integer Indicates whether the customer would like to get e-invoices (0 or 1).
mailEnabled Integer If e-invoice operator supports sending paper mails and this value is set to 1, then the operator is allowed to send the invoice by mail (additional charges might occur) (0 or 1).
operatorIdentifier String
gender String Gender: "male", "female" or empty string.
groupID Integer Customer group ID.
countryID Integer Country ID.
groupName String
payerID Integer Payer ID
phone String
mobile String
email String
fax String
code String National ID number (for persons) / Registry code (for companies).
birthday Date (yyyy-mm-dd) Person's birthday
integrationCode String Corresponding customer identifier in a system integrated with Erply (eg. accounting software)
flagStatus 0 or 1 Whether the customer is marked with an importance flag or not.
doNotSell 0 or 1 Whether the customer is marked with a do not sell flag or not.
colorStatus String Optional colored flag associated with this customer. Possible values: "", "red", "green", "yellow", "blue".
image String URL to customer's image file.
taxExempt Integer (0 or 1) Indicates this customer is a tax exempt organization.
factoringContractNumber String (255) Factoring contract number.
paysViaFactoring Integer (0 or 1) Indicates this customer pays invoices via factoring.
rewardPoints Integer Do not use. Does NOT return reward points information.
To retrieve customer's reward points balance, use getCustomerRewardPoints.
twitterID String
facebookName String
creditCardLastNumbers String Last 4 numbers of customer's credit card.
GLN String GLN.
EDI String EDI code.
isPOSDefaultCustomer Integer (0 or 1) Indicates this customer is a default customer.
euCustomerType String Customer type. Possible values are "DOMESTIC", "EU", "EU_WITH_VAT", "OUTSIDE_EU".
credit Integer Credit limit.
salesBlocked Integer 0 or 1, by default 0.
Indicates that this customer is not allowed to receive invoices (up-front cash payments only).
referenceNumber String Customer's reference number, if system is configured to use hand-assigned reference numbers (by default not).
customerCardNumber String Code of customer's loyalty/membership card. This code matches the sequence produced by card swipe.
rewardPointsDisabled Integer 0 or 1.
Indicates that this customer does not earn new reward points.
customerBalanceDisabled Integer 0 or 1.
Indicates that this customer ignores balance calculation.
posCouponsDisabled Integer 0 or 1.
Indicates that POS does not automatically print coupons to this customer.
emailOptOut Integer 0 or 1.
Indicates that this customer is opted-out customer.
lastModifierUsername String Employee's username
shipGoodsWithWaybills Integer 0 or 1.
Indicates that for this customer, shipments should be (and may be) accompanied by a Waybill. At the end of the month, a summary Invoice can be issued for all the month's shipments and customer will pay then for all the shipments at once. (In the Sales module, there is a command "Create invoice from selected waybills"). If a customer does not have this flag, you should issue Invoice-Waybills instead, and the customer must pay for each shipment separately.
Field appears only if conf parameter enable_waybill_customers is set to 1.
addresses Array All customer's postal addresses. To retrieve this element, set input parameter getAddresses to 1.

Each array item has the following attributes:

Field nameTypeDescription
addressIDIntegerAddress ID
addressStringFull formatted address, on one line. Address parts are joined by commas, eg:
145 West 64th St, Apartment 135, New York, NY 10067
streetStringStreet address
address2StringStreet address, line 2.
Only US, CA, MX, AU, DE, AT and CH users have this field in Erply.
cityStringCity, region, or county
postalCodeStringPostal code or ZIP code
stateStringState.
Only US, CA, MX, AU, DE, AT and CH users have this field in Erply.
countryString
typeIDIntegerAddress type ID
typeNameString (255)Address type
contactPersons Array All customer's contact persons. To retrieve this element, set input parameter getContactPersons to 1.

Each array item has the following attributes:

Field nameTypeDescription
contactPersonIDInteger
fullNameStringFull name of the contact person, use for displaying.
firstNameString
lastNameString
groupIDIntegerContact person's customer group ID.
groupNameStringContact person's group name.
phoneString
mobileString
emailString
faxString
codeStringNational ID number.
integrationCodeStringCorresponding identifier in a system integrated with Erply (eg. accounting software)
flagstatusInteger (0 or 1)
colorStatusStringOptional colored flag associated with this contact person. Possible values: "", "red", "green", "yellow", "blue".
imageStringURL to customer's image file.
twitterIDString
facebookNameString
customerCardNumberString
skypeString
websiteString
bankNameStringName of contact person's bank.
bankAccountNumberStringNumber of contact person's bank account.
bankIBANStringIBAN number of contact person's bank account.
bankSWIFTStringBIC/SWIFT identifier of contact person's bank account.
birthdayDate (yyyy-mm-dd)Person's birthday.
jobTitleIDIntegerPerson's job title.
jobTitleNameString
customerManagerIDIntegerContact person's customer manager.
customerManagerNameString
businessAreaIDIntegerContact person's business area.
businessAreaNameString
notesString
defaultAssociationID Integer Default association ID.
defaultAssociationName String Default association name.
defaultProfessionalID Integer Default professional ID.
defaultProfessionalName String Default professional name.
associations Array All customer's associations. To retrieve this element, set input parameter getAssociationsAndProfessionals to 1.

See the description of the getAssociationsAndProfessionals flag above, to learn what the "associations" and "professionals" are.

Each array item has the following attributes:

Field nameTypeDescription
relationshipIDInteger
idIntegerAssociation ID
nameStringAssociation name
defaultInteger (0 or 1)
professionals Array All customer's professionals. To retrieve this element, set input parameter getAssociationsAndProfessionals to 1.

See the description of the getAssociationsAndProfessionals flag above, to learn what the "associations" and "professionals" are.

Each array item has the following attributes:

Field nameTypeDescription
relationshipIDInteger
idIntegerProfessional ID
nameStringProfessional name
defaultInteger (0 or 1)
attributes Array Additional attributes. Each item looks like this:

Field nameTypeDescription
attributeNameStringAttribute name
attributeTypeStringAttribute type
attributeValueStringAttribute value
longAttributes Array Additional attributes — longer strings. Each item looks like this:

Field nameTypeDescription
attributeNameStringAttribute name
attributeValueStringAttribute value
externalIDs Array All customer's external IDs.

Each array item has the following attributes:

Field nameType
integrationNameString
externalIDInteger
**** **** Customer balance. To retrieve these fields, set input parameter getBalanceInfo to 1.

If you want to retrieve balances only, without customer information, take a look at API call getCustomerBalances.
actualBalance Decimal Amount that the customer has prepaid (NEGATIVE VALUE) or is currently due (POSITIVE VALUE). NB! The sign of the value is opposite to the usual expectation, since that's how balances are usually kept in accounting.
creditLimit Integer The credit limit that has been set to the customer.
availableCredit Decimal This value shows how much of the credit is actually available at the moment. availableCredit = creditLimit - actualBalance.
creditAllowed 0 or 1 If set to 0, customer cannot use the "pay later" option, and must pay up-front in full for each purchase.
**** **** To retrieve the following fields, set input parameter responseMode = "detail". These fields are not included in the output by default.
vatNumber String Customer's VAT number.
skype String
website String
webshopUsername String
webshopLastLogin String
bankName String Name of customer's bank.
bankAccountNumber String Number of customer's bank account.
bankIBAN String IBAN number of customer's bank account.
bankSWIFT String BIC/SWIFT identifier of customer's bank account.
jobTitleID Integer Person's job title ID
jobTitleName String
companyID Integer (Persons only.) Company where this person is an employee / a contact person.
employerName String
customerManagerID Integer Customer manager ID
customerManagerName String
paymentDays Integer Default payment period for invoices.
penaltyPerDay String Penalty for overdue invoices, expressed as % per day, eg. "0.5". Free text.
priceListID Integer Customer's price list 1
priceListID2 Integer Customer's price list 2
priceListID3 Integer Customer's price list 3
outsideEU 0 or 1, by default 0 Indicates that this is a foreign customer, located outside EU. DEPRECATED — euCustomerType is recommended instead.
businessAreaID Integer Customer's business area.
businessAreaName String
deliveryTypeID Integer
signUpStoreID Integer Location where customer was registered.
homeStoreID Integer Most commonly used location.
taxOfficeID Integer Tax office ID. This is a Greece-specific field and is only returned on Greek accounts.
notes String
lastModified Unix timestamp
lastModifierEmployeeID Integer ID of the employee
added Unix timestamp
**** **** Customer's first postal address.

A customer can have multiple addresses, and if you would like to retrieve them all, we rather recommend to set input parameter getAddresses to 1. API will then return an additional element "addresses".

However, if you do not need that detailed information and one address is enough, you may use these fields.

Furthermore, there are also API calls getAddresses and saveAddress for managing addresses.
address String Full formatted address, on one line. Address parts are joined by commas, eg:
145 West 64th St, Apartment 135, New York, NY 10067
street String (65536) Street address (or more generally, address line 1).
address2 String (65536) Street address, line 2.
Only US, CA, MX and AU users have this field in Erply.
city String (255) City, region, or county.
postalCode String (16) Postal code or ZIP code.
state String (255) State.
Only US, CA, MX and AU users have this field in Erply.
country String (255)
addressTypeID Integer Address type ID.
addressTypeName String (255) Address type.