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  Search from attribute name.searchAttributeName and searchAttributeValue have to be specified both  String    
searchAttributeValue  Search from attribute value  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    
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    
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).      
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)    
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' or 'none' (no ordering). By default 'name'.    
orderByDir    By default 'ASC'    
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 retrive the next recordsOnPage items, send a new request with pageNo incremented by one. By default, API returns "page 1".  Integer    

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.  
firstName  String  (Given name.) For persons only.  
lastName  String  (Surname.) For persons only.  
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  
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.  
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.  
isPOSDefaultCustomer  Integer (0 or 1)  Indicates this customer is a default customer.  
euCustomerType  String  Customer type. Possible values are "DOMESTIC", "EU", "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.  
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
 
****  ****  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.