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
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 "searchName" 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 only 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
partialTaxExemption		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 distinction 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 retrieve 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.

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 integer 0 or 1. Whether the customer is marked with an importance flag or not.

doNotSell integer 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.

partialTaxExemption Integer (0 or 1)

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.

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 name	Type	Description
addressID	Integer	Address ID
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	Street address
address2	String	Street address, line 2. Only US, CA, MX, AU, DE, AT and CH users have this field in Erply.
city	String	City, region, or county
postalCode	String	Postal code or ZIP code
state	String	State. Only US, CA, MX, AU, DE, AT and CH users have this field in Erply.
country	String
typeID	Integer	Address type ID
typeName	String (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 name	Type	Description
contactPersonID	Integer
fullName	String	Full name of the contact person, use for displaying.
firstName	String
lastName	String
groupID	Integer	Contact person's customer group ID.
groupName	String	Contact person's group name.
phone	String
mobile	String
email	String
fax	String
code	String	National ID number.
integrationCode	String	Corresponding identifier in a system integrated with Erply (eg. accounting software)
flagstatus	Integer (0 or 1)
colorStatus	String	Optional colored flag associated with this contact person. Possible values: "", "red", "green", "yellow", "blue".
image	String	URL to customer's image file.
twitterID	String
facebookName	String
customerCardNumber	String
skype	String
website	String
bankName	String	Name of contact person's bank.
bankAccountNumber	String	Number of contact person's bank account.
bankIBAN	String	IBAN number of contact person's bank account.
bankSWIFT	String	BIC/SWIFT identifier of contact person's bank account.
birthday	Date (yyyy-mm-dd)	Person's birthday.
jobTitleID	Integer	Person's job title.
jobTitleName	String
customerManagerID	Integer	Contact person's customer manager.
customerManagerName	String
businessAreaID	Integer	Contact person's business area.
businessAreaName	String
notes	String

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 name	Type	Description
relationshipID	Integer
id	Integer	Association ID
name	String	Association name
default	Integer (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 name	Type	Description
relationshipID	Integer
id	Integer	Professional ID
name	String	Professional name
default	Integer (0 or 1)

attributes

array

Additional attributes. Each item looks like this:

Field name	Type	Description
attributeName	String	Attribute name
attributeType	String	Attribute type
attributeValue	String	Attribute value

longAttributes

array

Additional attributes — longer strings. Each item looks like this:

Field name	Type	Description
attributeName	String	Attribute name
attributeValue	String	Attribute value

externalIDs

array

All customer's external IDs.

Each array item has the following attributes:

Field name	Type
integrationName	String
externalID	Integer

actualBalance number 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. To retrieve this field, set input parameter getBalanceInfo to 1.

If you want to retrieve balances only, without customer information, take a look at API call getCustomerBalances.

creditLimit integer The credit limit that has been set to the customer. To retrieve this field, set input parameter getBalanceInfo to 1.

If you want to retrieve balances only, without customer information, take a look at API call getCustomerBalances.

availableCredit number This value shows how much of the credit is actually available at the moment. availableCredit = creditLimit - actualBalance. To retrieve this field, set input parameter getBalanceInfo to 1.

If you want to retrieve balances only, without customer information, take a look at API call getCustomerBalances.

creditAllowed integer 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 this field, set input parameter getBalanceInfo to 1.

If you want to retrieve balances only, without customer information, take a look at API call getCustomerBalances.

Detail Response

Field name	Type	Description
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
priceListID4	integer	Customer's price list 4 (only on accounts that have the extra fields enabled)
priceListID5	integer	Customer's price list 5 (only on accounts that have the extra fields enabled)
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.
primaryStoreID	Integer/Null	Can be used in an e-commerce integration, to store the customer’s preferred pickup locations, for example — if it is necessary to distinguish those from the customer’s preferred store for in-person shopping ("homeStoreID").
secondaryStoreID	Integer/Null	Can be used in an e-commerce integration, to store the customer’s preferred pickup locations, for example — if it is necessary to distinguish those from the customer’s preferred store for in-person shopping ("homeStoreID").
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
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).
docuraEDIEnabled	Integer (0 or 1)
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.
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
EDI	string	EDI code.
PeppolID	string	Peppol ID.
GLN	string	GLN.
ediType	string	EDI type. Possible values: 2DOC, 4DOC, SPECIAL.
********	********	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.