API DOCUMENTATION
    Try Unleashed Now Sandbox

    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 of paginated Customers GET /Customers/Page/{pageNumber}
    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
    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
    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
    LastModifiedBy String 50
    LastModifiedOn Nullable DateTime
    MobileNumber String 500
    Notes String 1024
    Obsolete Boolean
    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
    Taxable Nullable Boolean
    TaxCode String 50
    TaxRate Nullable Decimal
    TollFreeNumber String 500
    Website String 500
    XeroCostOfGoodsAccount String 500
    XeroSalesAccount String 500

    Examples for GET /Customers

    show xml example
    show json example

    GET Customer Contacts

    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
    ForInvoicing Boolean
    ForOrdering Boolean
    ForShipping Boolean
    FirstName String 500
    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

    Examples for GET /CustomerContacts

    show xml example
    show json example

    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
    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 DefaultWarehouse

    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

    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 At least a FirstName, LastName or EmailAddress must be provided. Optional Optional
    FaxNumber String 500
    FirstName String 500 At least a FirstName, LastName or EmailAddress must be provided. 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 At least a FirstName, LastName or EmailAddress must be provided. 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

    Examples for PUT /Customers/{CustomerGuid}/Contacts/{ContactGuid}

    show xml example
    show json example

    Use the API Sandbox to see how the object is rendered in JSON or XML.

    Note: An Unleashed account is required before you can use the API Sandbox.

    Trial accounts are also allowed to connect to the API.
    You can register a new account here: Register.