Customers
The Customers resource allows Customers to be viewed, created, and updated. An individual Customer’s details can be viewed, or updated by appending its identifier (a GUID formatted as XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
) to the URI.
The full range of URIs and HTTP Verbs supported are:
Operation
HTTP Action
List a page of Customers
GET /Customers
View any Customer
GET /Customers/{customerGuid}
List all contacts for a specific Customer
GET /Customers/{customerGuid}/Contacts
Create or update a Customer
POST /Customers/{customerGuid}
Create a new Customer Contact
POST /Customers/{customerGuid}/Contacts
Update an existing Customer Contact
PUT /Customers/{customerGuid}/Contacts/{contactGuid}
Delete an existing Customer Contact
DELETE /Customers/{customerGuid}/Contacts/{contactGuid}
GET Customers
Available Filters for GET Customers
Filter
Description
contactEmail
Only returns Customers that have a contact email that starts with the specified email address.
currency
Only returns Customers with currency code exactly matching the specified value.
customer
Returns Customers whose customer code or customer name contains the specified value. It is case-sensitive.
customerCode
Only returns Customers that start with the specific customer code.
customerName
Only returns Customers that start with the specific customer name.
customerType
Only returns Customers that matches the specified customer type.
includeAllContacts
Returns the first 100 contacts of each Customer record, if set to true. If set to false only the primary contact details will be returned as part of the response.
includeObsolete
Returns all Customers, including obsolete, if set to true. If set to false or if it is not specified then returns only active (ie. non-obsolete) Customers.
modifiedSince
Returns Customers created or modified since the specified date.
orderBy
Orders the list by LastModifiedOn
or CreatedOn
date. By default the list is ordered by CustomerCode
pageSize
Specifies the page size for pagination. Default page size is 200 customers.
Note: Requesting large numbers of customers can be susceptible to poor network performance. Please reduce the page size if you experience delayed requests.
salesOrderGroup
Only returns Customers with the specified sales order group.
sellPriceTier
Only returns Customers that are assigned to the specified sell price tier.
sort
Orders the list by CreatedOn
date sorted in ascending or descending order.
stopCredit
Returns Customers who have had their credit stopped, if set to true. If set to false or if not specified, returns all customers.
xeroContactId
Only returns Customers that start with the specific Xero Contact Id.
Note: Date filters should be provided in the ISO format YYYY-MM-DD.
Filters are used by adding the filter and value to the URI:
/Customers?customerCode=ACME&includeObsolete=true
/Customers?orderBy=CreatedOn
- returns Customers ordered by created on date sorted in ascending order
/Customers?orderBy=CreatedOn&sort=desc
- returns Customers ordered by created on date sorted in descending order
Available Fields for GET Customers
Property
Type
Length
Addresses
Address collection
BankAccount
String
500
BankBranch
String
500
BankName
String
500
Contacts
Contact collection
ContactFirstName
String
500
ContactLastName
String
500
CreatedBy
String
50
CreatedOn
Nullable DateTime
CreditLimit
Decimal
Currency
Currency
CustomerCode
String
500
CustomerName
String
500
CustomerType
String
50
CustomerTypeGuid
Guid
DDINumber
String
500
DefaultWarehouse
DefaultWarehouse
DeliveryInstruction
String
500
DeliveryMethod
String
50
DiscountRate
Nullable Decimal
Email
String
500
EmailCC
String
500
EORINumber
String
20
FaxNumber
String
500
GSTVATNumber
String
500
Guid
Guid
HasCreditLimit
Boolean
true
, false
LastModifiedBy
String
50
LastModifiedOn
Nullable DateTime
MobileNumber
String
500
Notes
String
1024
Obsolete
Boolean
true
, false
PaymentTerm
String
100
PhoneNumber
String
500
PrintInvoice
Nullable Boolean
PrintPackingSlipInsteadOfInvoice
Nullable Boolean
Reminder
String
1024
SalesOrderGroup
String
50
Salesperson
Salesperson
SellPriceTier
String
25
SellPriceTierReference
SellPriceTierReference
StopCredit
Boolean
true
, false
Taxable
Nullable Boolean
TaxCode
String
50
TaxRate
Nullable Decimal
TollFreeNumber
String
500
Website
String
500
XeroCostOfGoodsAccount
String
500
XeroSalesAccount
String
500
Available Fields for GET Address
Property
Type
Length
AddressName
String
500
AddressType
String
20
City
String
500
Country
String
500
DeliveryInstruction
String
500
Guid
Guid
IsDefault
Boolean
true
, false
LastModifiedOn
DateTime
PostalCode
String
500
Region
String
500
StreetAddress
String
500
StreetAddress2
String
500
Suburb
String
500
Available Fields for GET Contact
Property
Type
Length
DeliveryAddress
String
500
DDINumber
String
500
EmailAddress
String
500
FaxNumber
String
500
FirstName
String
500
ForInvoicing
Boolean
true
, false
ForOrdering
Boolean
true
, false
ForShipping
Boolean
true
, false
Guid
Guid
500
IsDefault
Boolean
true
, false
LastName
String
500
MobilePhone
String
500
Notes
String
1024
OfficePhone
String
500
PhoneNumber
String
500
TollFreeNumber
String
500
Website
String
500
Available Fields for GET Currency
Property
Type
Length
CurrencyCode
String
3
DefaultBuyRate
Nullable Decimal
DefaultSellRate
Nullable Decimal
Description
String
200
Guid
Guid
LastModifiedOn
DateTime
Available Fields for GET Default Warehouse
Property
Type
Length
Guid
Guid
WarehouseCode
String
15
WarehouseName
String
100
Available Fields for GET Salesperson
Property
Type
Length
Email
String
256
FullName
String
256
Guid
Guid
LastModifiedOn
DateTime
Obsolete
Boolean
true
, false
Examples for GET /Customers
show xml example
<?xml version="1.0"?>
<Customers xmlns:xsd= "http://www.w3.org/2001/XMLSchema" xmlns:xsi= "http://www.w3.org/2001/XMLSchema-instance" xmlns= "http://api.unleashedsoftware.com/version/1" >
<Pagination>
<NumberOfItems> 1</NumberOfItems>
<PageSize> 200</PageSize>
<PageNumber> 1</PageNumber>
<NumberOfPages> 1</NumberOfPages>
</Pagination>
<Customer>
<Guid> b9f21e05-07fe-4d9d-b460-a09db4c3caa1</Guid>
<LastModifiedOn> 2019-08-06T01:40:17.0039206</LastModifiedOn>
<Addresses>
<Address>
<AddressType> Shipping</AddressType>
<AddressName> Main Warehouse</AddressName>
<StreetAddress> 31 Hurstmere Road</StreetAddress>
<Suburb> Takapuna</Suburb>
<City> Auckland</City>
<Region> North Shore</Region>
<Country> New Zealand</Country>
<PostalCode> 0622</PostalCode>
<IsDefault> false</IsDefault>
<DeliveryInstruction> Handle with care.</DeliveryInstruction>
<LastModifiedOn> 2024-05-28T22:11:09.6589976</LastModifiedOn>
<Guid> aeae2924-4d66-413c-8faf-463e50d3dc65</Guid>
</Address>
</Addresses>
<TaxCode />
<TaxRate xsi:nil= "true" />
<CustomerCode> WADE2</CustomerCode>
<CustomerName> Wade's Apparel & Accessories2</CustomerName>
<Currency>
<Guid> 6cb5d67a-1c96-4fa8-bf59-b23c2d69f22a</Guid>
<LastModifiedOn> 2019-06-05T23:42:47.5066667</LastModifiedOn>
<CurrencyCode> NZD</CurrencyCode>
<Description> New Zealand, Dollars</Description>
</Currency>
<Taxable> true</Taxable>
<DiscountRate> 0.0000</DiscountRate>
<PrintPackingSlipInsteadOfInvoice> false</PrintPackingSlipInsteadOfInvoice>
<PrintInvoice> false</PrintInvoice>
<StopCredit> false</StopCredit>
<Obsolete> false</Obsolete>
<SellPriceTier />
<CustomerType> Cash</CustomerType>
<CustomerTypeGuid> 6b60e9ce-4e1a-40da-bc0c-144ec9a9958a</CustomerTypeGuid>
<PaymentTerm> 20th Month following</PaymentTerm>
<CreatedBy> support@unleashedsoftware.com</CreatedBy>
<CreatedOn> 2019-08-06T01:35:34.6502961</CreatedOn>
<LastModifiedBy> support@unleashedsoftware.com</LastModifiedBy>
</Customer>
</Customers>
show json example
{
"Pagination" : {
"NumberOfItems" : 1 ,
"PageSize" : 200 ,
"PageNumber" : 1 ,
"NumberOfPages" : 1
},
"Items" : [
{
"Addresses" : [
{
"AddressType" : "Shipping" ,
"AddressName" : "Main Warehouse" ,
"StreetAddress" : "31 Hurstmere Road" ,
"StreetAddress2" : null ,
"Suburb" : "Takapuna" ,
"City" : "Auckland" ,
"Region" : "North Shore" ,
"Country" : "New Zealand" ,
"PostalCode" : "0622"
"IsDefault" : false ,
"DeliveryInstruction" : "Handle with care." ,
"LastModifiedOn" : "/Date(1716934269658)/" ,
"Guid" : "9a1effae-f705-45e0-bc87-409e567f7de4"
}
],
"TaxCode" : "" ,
"TaxRate" : null ,
"CustomerCode" : "WADE" ,
"CustomerName" : "Wade's Apparel & Accessories" ,
"GSTVATNumber" : null ,
"BankName" : null ,
"BankBranch" : null ,
"BankAccount" : null ,
"Website" : null ,
"PhoneNumber" : null ,
"FaxNumber" : null ,
"MobileNumber" : null ,
"DDINumber" : null ,
"TollFreeNumber" : null ,
"Email" : null ,
"EmailCC" : null ,
"Currency" : {
"CurrencyCode" : "NZD" ,
"Description" : "New Zealand, Dollars" ,
"Guid" : "6cb5d67a-1c96-4fa8-bf59-b23c2d69f22a" ,
"LastModifiedOn" : " \/ Date(1559778167506) \/ "
},
"Notes" : null ,
"Taxable" : true ,
"Salesperson" : null ,
"DiscountRate" : 0.0000 ,
"PrintPackingSlipInsteadOfInvoice" : false ,
"PrintInvoice" : false ,
"StopCredit" : false ,
"Obsolete" : false ,
"XeroSalesAccount" : null ,
"XeroCostOfGoodsAccount" : null ,
"SellPriceTier" : "" ,
"SellPriceTierReference" : null ,
"CustomerType" : "Cash" ,
"CustomerTypeGuid" : "6b60e9ce-4e1a-40da-bc0c-144ec9a9958a" ,
"PaymentTerm" : "20th Month following" ,
"ContactFirstName" : null ,
"ContactLastName" : null ,
"CreatedBy" : "support@unleashedsoftware.com" ,
"CreatedOn" : " \/ Date(1496706437136) \/ " ,
"LastModifiedBy" : "support@unleashedsoftware.com" ,
"Guid" : "b9f21e05-07fe-4d9d-b460-a09db4c3caa9" ,
"LastModifiedOn" : " \/ Date(1559778437146) \/ "
}
]
}
Available Filters for GET Customer Contacts
Filter
Description
orderBy
Orders the list by LastModifiedOn
or CreatedOn
date. By default the list is ordered by Primary Contact then alphabetically by First Name, Last Name.
page
Specifies which page number will be shown.
pageSize
Specifies the page size for pagination, the default page size is 200 customer contacts.
Note: Requesting large numbers of customer contacts can be susceptible to poor network performance. Please reduce the page size if you experience delayed requests.
sort
Orders the list by CreatedOn
date sorted in ascending or descending order.
Filters are used by adding the filter and value to the URI:
/Customers/{CustomersGuid}/Contacts?orderBy=CreatedOn&sort=asc
- returns a customer’s contacts, ordered by created on date sorted in ascending order
Available Fields for GET Customer Contacts
Property
Type
Length
Notes
DeliveryAddress
String
500
Delivery Address name
DDINumber
String
500
EmailAddress
String
500
FaxNumber
String
500
FirstName
String
500
ForInvoicing
Boolean
ForOrdering
Boolean
ForShipping
Boolean
Guid
Guid
500
IsDefault
Boolean
LastName
String
500
MobilePhone
String
500
Notes
String
1024
OfficePhone
String
500
PhoneNumber
String
500
TollFreeNumber
String
500
Website
String
500
show xml example
show json example
<?xml version="1.0"?>
<CustomerContacts xmlns:xsd= "http://www.w3.org/2001/XMLSchema" xmlns:xsi= "http://www.w3.org/2001/XMLSchema-instance" xmlns= "http://api.unleashedsoftware.com/version/1" >
<CustomerContact>
<EmailAddress> hsmith@company.com</EmailAddress>
<FirstName> Harold</FirstName>
<LastName> Smith</LastName>
<Guid> 2af29a88-ce12-45b9-84c1-26e4d2d10227</Guid>
<ForInvoicing> true</ForInvoicing>
<ForShipping> false</ForShipping>
<ForOrdering> false</ForOrdering>
<IsDefault> true</IsDefault>
</CustomerContact>
<CustomerContact>
<Guid> e9086f56-6966-4599-9b69-c96aa973e981</Guid>
<ForInvoicing> false</ForInvoicing>
<ForShipping> false</ForShipping>
<ForOrdering> false</ForOrdering>
<IsDefault> false</IsDefault>
</CustomerContact>
</CustomerContacts>
{
"Pagination" : null ,
"Items" : [
{
"ForInvoicing" : true ,
"ForShipping" : false ,
"ForOrdering" : false ,
"IsDefault" : true ,
"DDINumber" : null ,
"EmailAddress" : "hsmith@company.com" ,
"FaxNumber" : null ,
"FirstName" : "Harold" ,
"LastName" : "Smith" ,
"MobilePhone" : "123456789" ,
"Notes" : null ,
"OfficePhone" : null ,
"PhoneNumber" : null ,
"TollFreeNumber" : null ,
"Website" : null ,
"Guid" : "2af29a88-ce12-45b9-84c1-26e4d2d10227" ,
"DeliveryAddress" : "Company Warehouse 5"
},
{
"ForInvoicing" : false ,
"ForShipping" : false ,
"ForOrdering" : false ,
"IsDefault" : false ,
"DDINumber" : null ,
"EmailAddress" : null ,
"FaxNumber" : null ,
"FirstName" : null ,
"LastName" : null ,
"MobilePhone" : null ,
"Notes" : null ,
"OfficePhone" : null ,
"PhoneNumber" : null ,
"TollFreeNumber" : null ,
"Website" : null ,
"Guid" : "e9086f56-6966-4599-9b69-c96aa973e981" ,
"DeliveryAddress" : null
},
]
}
POST Customers
Available Fields for POST Customer
Note: Any changes to the Primary Contact, requires Primary contact details with ContactFirstName
, ContactLastName
, and/or Email
to be supplied. Updates made to existing Primary Contact will overwrite existing information, fields left blank will be removed.
Property
Type
Length
Required
Notes
Addresses
Address
You can have the following Address Types: Postal, Physical, and Shipping.
BankAccount
String
500
BankBranch
String
500
BankName
String
500
ContactFirstName
String
500
See notes
Only the Primary Contact can be created or updated via the API.
ContactLastName
String
500
See notes
Only the Primary Contact can be created or updated via the API.
CreditLimit
Decimal
Currency
Currency
CustomerCode
String
500
Yes
Unique code. Can only be set when creating a Customer.
CustomerName
String
500
Yes
CustomerType
String
50
If CustomerTypeGuid is also provided, it must match the same Customer Type.
CustomerTypeGuid
Guid
If CustomerType is also provided, it must match the same Customer Type.
DDINumber
String
500
If supplied, Primary Contact details are required.
DefaultWarehouse
DefaultWarehouse
DeliveryInstruction
String
500
When updating, null or missing property will not override existing information.
DeliveryMethod
String
50
DiscountRate
Decimal
Email
String
500
See notes
Email address format validated. Only the Primary Contact can be created or updated via the API.
EmailCC
String
500
Email address format validated. Multiple email addresses must be comma separated.
EORINumber
String
20
FaxNumber
String
500
If supplied, Primary Contact details are required.
GSTVATNumber
String
500
Guid
Guid
Yes
Unique identifier. Can only be set when adding a record. Must match the Guid in the request URL
HasCreditLimit
Boolean
MobileNumber
String
500
If supplied, Primary Contact details are required.
Notes
String
1024
Obsolete
Boolean
PaymentTerm
String
100
PhoneNumber
String
500
If supplied, Primary Contact details are required.
PrintInvoice
Boolean
PrintPackingSlipInsteadOfInvoice
Boolean
Salesperson
Salesperson
SalesOrderGroup
String
50
SellPriceTier
String
25
SellPriceTierReference
SellPriceTierReference
StopCredit
Boolean
Taxable
Boolean
TaxCode
String
50
Code of the default tax selected on the customer.
TaxRate
Decimal
Rate of the default tax selected on the customer.
TollFreeNumber
String
500
If supplied, Primary Contact details are required.
Website
String
500
Website format validated. If supplied, Primary Contact details are required.
XeroCostOfGoodsAccount
String
500
XeroSalesAccount
String
500
Available Fields for Address
Property
Type
Length
Required
Notes
AddressName
String
500
AddressType
String
20
City
String
500
Country
String
500
Either CountryCode or CountryName can be provided. 2 character country codes are validated against the ISO 3166 list
PostalCode
String
500
Region
String
500
StreetAddress
String
500
StreetAddress2
String
500
Suburb
String
500
Available Fields for Currency
Note: At a minimum, a valid Guid
or CurrencyCode
is required.
Property
Type
Length
CurrencyCode
String
3
Guid
Guid
Available Fields for Default Warehouse
Note: At a minimum, a valid Guid
or WarehouseCode
is required.
Property
Type
Length
Guid
Guid
WarehouseCode
String
15
Available Fields for Salesperson
Property
Type
Length
Required
Email
String
256
FullName
String
256
Guid
Guid
Yes
Examples for POST /Customers/{customerGuid}
show xml example
show json example
<?xml version="1.0"?>
<Customer xmlns:xsd= "http://www.w3.org/2001/XMLSchema" xmlns:xsi= "http://www.w3.org/2001/XMLSchema-instance" xmlns= "http://api.unleashedsoftware.com/version/1" >
<Guid> faf526bc-baaa-42d0-81ed-64c3148554a0</Guid>
<Addresses>
<Address>
<AddressType> Shipping</AddressType>
<AddressName> Example Shipping</AddressName>
<StreetAddress> 44-42226 Morningside Road</StreetAddress>
<Suburb> Edinburgh</Suburb>
<City> Edinburgh</City>
<Region> Scotland</Region>
<Country> United Kingdom</Country>
<PostalCode> EH10 4BF</PostalCode>
<IsDefault> false</IsDefault>
</Address>
<Address>
<AddressType> Postal</AddressType>
<AddressName> Example Postal</AddressName>
<StreetAddress> 44-42226 Morningside Road</StreetAddress>
<Suburb> Edinburgh</Suburb>
<City> Edinburgh</City>
<Region> Scotland</Region>
<Country> United Kingdom</Country>
<PostalCode> EH10 4BF</PostalCode>
<IsDefault> false</IsDefault>
</Address>
</Addresses>
<CustomerCode> SIREEN</CustomerCode>
<CustomerName> The House of Sireen</CustomerName>
<Email> support@unleashedsoftware.com</Email>
<EmailCC> support@unleashedsoftware.com</EmailCC>
<Currency>
<Guid> 21776179-8c51-4c1f-9eb8-9e6b4ff66c23</Guid>
<CurrencyCode> GBP</CurrencyCode>
<Description> United Kingdom, Pounds</Description>
</Currency>
<Taxable> true</Taxable>
<DiscountRate> 0.0000</DiscountRate>
<PrintPackingSlipInsteadOfInvoice> false</PrintPackingSlipInsteadOfInvoice>
<PrintInvoice> false</PrintInvoice>
<StopCredit> false</StopCredit>
<Obsolete> false</Obsolete>
<CustomerType> Cash</CustomerType>
<CustomerTypeGuid> 6b60e9ce-4e1a-40da-bc0c-144ec9a9958a</CustomerTypeGuid>
<PaymentTerm> 20th Month following</PaymentTerm>
<ContactFirstName> two</ContactFirstName>
<ContactLastName> two</ContactLastName>
</Customer>
{
"Guid" : "59f21e05-07fe-4d9d-b460-a09db4c3caa9" ,
"Addresses" : [
{
"AddressType" : "Shipping" ,
"AddressName" : "Example Address" ,
"StreetAddress" : "Example Address" ,
"StreetAddress2" : "Example Address 2" ,
"Suburb" : "Example Suburb" ,
"City" : "Auckland" ,
"Region" : "Auckland" ,
"Country" : "New Zealand" ,
"PostalCode" : "1061" ,
"IsDefault" : false ,
"DeliveryInstruction" : "Have a good day"
}
],
"CustomerCode" : "UnleashedCustomer" ,
"CustomerName" : "Unleashed Customer" ,
"Currency" : {
"CurrencyCode" : "NZD" ,
"Description" : "New Zealand, Dollars" ,
"Guid" : "6cb5d67a-1c96-4fa8-bf59-b23c2d69f22a"
},
"Taxable" : true ,
"DiscountRate" : 0.0000 ,
"PrintPackingSlipInsteadOfInvoice" : false ,
"PrintInvoice" : false ,
"StopCredit" : false ,
"Obsolete" : false ,
"CustomerType" : "Cash" ,
"CustomerTypeGuid" : "6b60e9ce-4e1a-40da-bc0c-144ec9a9958a" ,
"PaymentTerm" : "20th Month following"
}
POST/PUT Customer Contacts
Available Fields for POST/PUT Customer Contacts
Note: At a minimum, a valid FirstName
, LastName
, and/or EmailAddress
are required, and the combination of the three must be unique.
Warning: POST does not accept user-generated GUIDs.
Property
Type
Length
Notes
POST
PUT
DeliveryAddress
String
500
If supplied, must match an existing Delivery Address name.
DDINumber
String
500
EmailAddress
String
500
See notes
Optional
Optional
FaxNumber
String
500
FirstName
String
500
See notes
Optional
Optional
ForInvoicing
Boolean
ForOrdering
Boolean
ForShipping
Boolean
Guid
Guid
500
N/A
Required
IsDefault
Boolean
If there are no existing contacts for the customer, this contact will become the customer's default contact
LastName
String
500
See notes
Optional
Optional
MobilePhone
String
500
Notes
String
1024
OfficePhone
String
500
PhoneNumber
String
500
TollFreeNumber
String
500
Website
String
500
Examples for POST /Customers/{customerGuid}/Contacts
show xml example
show json example
<?xml version="1.0"?>
<CustomerContact xmlns:xsd= "http://www.w3.org/2001/XMLSchema" xmlns:xsi= "http://www.w3.org/2001/XMLSchema-instance" xmlns= "http://api.unleashedsoftware.com/version/1" >
<EmailAddress> jwhite@company.com</EmailAddress>
<FirstName> Joshua</FirstName>
<LastName> White</LastName>
<ForInvoicing> true</ForInvoicing>
<IsDefault> true</IsDefault>
</CustomerContact>
{
"ForInvoicing" : true ,
"IsDefault" : true ,
"EmailAddress" : "jwhite@company.com" ,
"FirstName" : "Joshua" ,
"LastName" : "White" ,
}
show xml example
show json example
<?xml version="1.0"?>
<CustomerContact xmlns:xsd= "http://www.w3.org/2001/XMLSchema" xmlns:xsi= "http://www.w3.org/2001/XMLSchema-instance" xmlns= "http://api.unleashedsoftware.com/version/1" >
<EmailAddress> jwhite@company.com</EmailAddress>
<FirstName> Joshua</FirstName>
<LastName> White</LastName>
<Guid> 9a714b72-36ac-490a-993f-b1ea7cf44161</Guid>
<IsDefault> true</IsDefault>
<MobilePhone> 314159268</MobilePhone>
</CustomerContact>
{
"ForInvoicing" : true ,
"IsDefault" : true ,
"EmailAddress" : "jwhite@company.com" ,
"FirstName" : "Joshua" ,
"LastName" : "White" ,
"MobilePhone" : "314159268" ,
"Guid" : "6618e38d-4bda-4239-873b-55d7a080967b" ,
}