Search

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.

Input parameters

Parameter nameDescriptionPossible valueRequired
customerIDCustomer's IDInteger
customerIDsList of customer ID's, separated by commas, eg. "1,2,3,4,5". (Do not put spaces around commas.)String
searchFromMiddleIf 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
searchNameSearch 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
searchNameIncrementallyA 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!
String
searchPersonFullNameSearch 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
searchPersonFirstNameSearch by person first name. Exact matches only.String
searchPersonLastNameSearch by person last name. Exact matches only.String
searchVATNoSearch by customer VAT no (field vatNumber). Exact matches only.String
searchCodeSearch by customer card # (field customerCardNumber). Exact matches only.String
searchRegistryCodeSearch by company registry code or person's national ID (field "code"). Exact matches only.String
searchAttributeNameSearch from attribute name.searchAttributeName and searchAttributeValue have to be specified bothString
searchAttributeValueSearch from attribute valueString
clientManagerIDCustomer manager. (See getEmployees.)Integer
groupIDRetrieve customers in this specific customer group. (See getCustomerGroups.)Integer
groupIDWithSubgroupsRetrieve 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
payerIDPayer ID.Integer
taxOfficeIDFilter 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
flagStatusWhether the customer is marked with an importance flag or not.0 or 1
colorStatusOptional colored flag associated with this customer. Possible values: "", "red", "green", "yellow", "blue".String
modeCUSTOMERS, 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
getBalanceInfoIf 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)
getBalanceWithoutPrepaymentsInteger (0 or 1)
getPurchaseInfoDeprecated, does not return any data.Integer (0 or 1)
getPOSDefaultCustomersIf set to 1, API returns all default customers used for POS transactionsInteger (0 or 1)
getAddressesSet 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 infortmation, take a look at API call getAddresses.
Integer (0 or 1)
getContactPersonsSet 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)
doNotCalculateRecordsTotalIf 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)
createdUnixTimeFromGet all new items that have been added since a specific point in time.Integer (Unix timestamp)
createdUnixTimeToGet all new items that have been added before a specific point in time.Integer (Unix timestamp)
changedSinceRetrieve 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)
langRetrieve 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'.
orderByDirBy default 'ASC'
recordsOnPageNumber of records API should return. By default 20, at most 100.Integer
pageNoAPI 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 nameTypeDescription
customerIDInteger(deprecated alternative name: id)
customerTypeStringCOMPANY 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.
fullNameStringFull name of the customer, use for displaying customer name.
companyNameStringFor companies only.
firstNameString(Given name.) For persons only.
lastNameString(Surname.) For persons only.
genderStringGender: "male", "female" or empty string.
groupIDIntegerCustomer group ID.
countryIDIntegerCountry ID.
groupNameString
payerIDIntegerPayer ID
phoneString
mobileString
emailString
faxString
codeStringNational ID number (for persons) / Registry code (for companies).
birthdayDate (yyyy-mm-dd)Person's birthday
integrationCodeStringCorresponding customer identifier in a system integrated with Erply (eg. accounting software)
flagStatus0 or 1Whether the customer is marked with an importance flag or not
colorStatusStringOptional colored flag associated with this customer. Possible values: "", "red", "green", "yellow", "blue".
imageStringURL to customer's image file.
taxExemptInteger (0 or 1)Indicates this customer is a tax exempt organization.
paysViaFactoringInteger (0 or 1)Indicates this customer pays invoices via factoring.
rewardPointsIntegerDo not use. Does NOT return reward points information.
To retrieve customer's reward points balance, use getCustomerRewardPoints.
twitterIDString
facebookNameString
creditCardLastNumbersStringLast 4 numbers of customer's credit card.
isPOSDefaultCustomerInteger (0 or 1)Indicates this customer is a default customer.
euCustomerTypeStringCustomer type. Possible values are "DOMESTIC", "EU", "OUTSIDE_EU".
creditIntegerCredit limit.
salesBlockedInteger0 or 1, by default 0.
Indicates that this customer is not allowed to receive invoices (up-front cash payments only).
referenceNumberStringCustomer's reference number, if system is configured to use hand-assigned reference numbers (by default not).
customerCardNumberStringCode of customer's loyalty/membership card. This code matches the sequence produced by card swipe.
rewardPointsDisabledInteger0 or 1.
Indicates that this customer does not earn new reward points.
posCouponsDisabledInteger0 or 1.
Indicates that POS does not automatically print coupons to this customer.
emailOptOutInteger0 or 1.
Indicates that this customer is opted-out customer.
lastModifierUsernameStringEmployee's username
shipGoodsWithWaybillsInteger0 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.
addressesArrayAll 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
contactPersonsArrayAll 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
defaultAssociationIDIntegerDefault association ID.
defaultAssociationNameStringDefault association name.
defaultProfessionalIDIntegerDefault professional ID.
defaultProfessionalNameStringDefault professional name.
associationsArrayAll 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)
professionalsArrayAll 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)
attributesArrayAdditional attributes. Each item looks like this:

Field nameTypeDescription
attributeNameStringAttribute name
attributeTypeStringAttribute type
attributeValueStringAttribute value
longAttributesArrayAdditional 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.
actualBalanceDecimalAmount 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.
creditLimitIntegerThe credit limit that has been set to the customer.
availableCreditDecimalThis value shows how much of the credit is actually available at the moment. availableCredit = creditLimit - actualBalance.
creditAllowed0 or 1If 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.
vatNumberStringCustomer's VAT number.
skypeString
websiteString
webshopUsernameString
webshopLastLoginString
bankNameStringName of customer's bank.
bankAccountNumberStringNumber of customer's bank account.
bankIBANStringIBAN number of customer's bank account.
bankSWIFTStringBIC/SWIFT identifier of customer's bank account.
jobTitleIDIntegerPerson's job title ID
jobTitleNameString
companyIDInteger(Persons only.) Company where this person is an employee / a contact person.
employerNameString
customerManagerIDIntegerCustomer manager ID
customerManagerNameString
paymentDaysIntegerDefault payment period for invoices.
penaltyPerDayStringPenalty for overdue invoices, expressed as % per day, eg. "0.5". Free text.
priceListIDIntegerCustomer's price list 1
priceListID2IntegerCustomer's price list 2
priceListID3IntegerCustomer's price list 3
outsideEU0 or 1, by default 0Indicates that this is a foreign customer, located outside EU. DEPRECATED — euCustomerType is recommended instead.
businessAreaIDIntegerCustomer's business area.
businessAreaNameString
deliveryTypeIDInteger
signUpStoreIDIntegerLocation where customer was registered.
homeStoreIDIntegerMost commonly used location.
taxOfficeIDIntegerTax office ID. This is a Greece-specific field and is only returned on Greek accounts.
notesString
lastModifiedUnix timestamp
lastModifierEmployeeIDIntegerID of the employee
addedUnix 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.
addressStringFull formatted address, on one line. Address parts are joined by commas, eg:
145 West 64th St, Apartment 135, New York, NY 10067
streetString (65536)Street address (or more generally, address line 1).
address2String (65536)Street address, line 2.
Only US, CA, MX and AU users have this field in Erply.
cityString (255)City, region, or county.
postalCodeString (16)Postal code or ZIP code.
stateString (255)State.
Only US, CA, MX and AU users have this field in Erply.
countryString (255)
addressTypeIDIntegerAddress type ID.
addressTypeNameString (255)Address type.