REST API Entity - Customers

This s a documentation page for our shiny new REST API - you weren't meant to find it. This API isn't ready for public use yet. We're chopping and changing it a LOT as we grow it. So if you build something that uses it then it's very likely to break in a future update. Don't say you weren't warned!

URL:	https://api.kashflow.com/v2/customers
Method(s):	get, post, put, delete
Response Formats:	JSON or XML
Description:	This method allows you to retrieve, create, update or delete a customer. The individual resource is identified by the customer code. So /customers/SHA01 would return the customer with code ‘SHA01’. Similarly a PUT to that URL would update customer SHA01.

Parameters

Name	Type	Description
Code	String	Unique code used to represent a customer
DisplayName	String	Customer name formatted according to user setting
Name	String	Customer’s name
Source	Numeric	Source
CreatedDate	Date	Date of customer creation. For e.g. [JSONDATE]
LastUpdatedDate	Date	Last date when customer was updated. For e.g. [JSONDATE]
IsRegisteredInEC	Boolean	Flag indicating whether customer is from european country or not .
IsRegisteredOutsideEC	Boolean	Flag indicates whether customer is from outside European country.
Note	String	Note
DiscountRate	Numeric	Discount (in percentage, 0-100 value) applied when a new invoice created for this customer.
ShowDiscount	Boolean	Flag indicating whether to show discount on Invoice or not
VatNumber	String	Vat number of the customer
AutoIncludeVATNumber	Boolean	Flag indicating whether to show VAT number on newly created invoices.If set to true VAT number will be automatically added to the invoice as a comment line.
TotalPaidAmount	Numeric	Total amount paid.
InvoicedNetAmount	Numeric	Invoice net amount for customer.
InvoicedVATAmount	Numeric	Invoice VAT amount for customer.
UseCustomDeliveryAddress	Boolean	Flag indicating whether user has a delivery address or not.
ReceivesWholesalePricing	Boolean	Flag indicating whether to receive discount in pricing. This is relevant when using autocomplete fields of a nominal code.
DefaultNominalCode	Numeric	Default Charge type is the default sales type with which invoice for this customer is created
IsArchived	Boolean	Flag indicating whether user is archived or not.
InvoiceCount	Numeric	The total number of invoices ever raised for this customer.
Currency	Object	Currency related information including code, name and symbol
DefaultCustomerReference	String	Default customer reference
EmailTemplateNumber	Numeric	The default email template to use when emailing invoices to this customer
OverrideInvoiceFileFormat	Boolean	Flag indicationg whether or not to override the account default setting for the filename given to PDFs when producing an invoice
InvoiceFileFormat	String	Invoice file format
FirstInvoiceDate	Date	The date of the first invoice for this customer. For e.g. [JSONDATE]
LastInvoiceDate	Date	The date of the last invoice for this customer. For e.g. [JSONDATE]
UniqueEntityNumber	String	Unique entity number. In some countries all companies have a UEN. This field is only shown in the UI if it has been enabled in the settings for the account
AutomaticCreditControlEnabled	Boolean	Flag indicating whether automatic credit control is enabled or not
Contacts	Object	This object contains an array of customers contact information like Telephone, FAX, Mobile, Website
Addresses	Object	This object contains customer address information like Line1, Line2, Line3, Line4, postCode, CountryCode and CountryName
DeliveryAddresses	Object	Customer delivery address information like name, Line1, Line2, Line3, Line4, postCode, CountryCode and CountryName
CustomTextBoxes	Collection	Collection of key value pair where key is the name of text box field shown on UI and value is the corresponding value of the textbox.
CustomCheckBoxes	Collection	Collection of key value pair where key is the name of check box field shown on UI and value is the corresponding value of the checkbox.Allowed value is 0 or 1
ApplyWHT	Boolean	WHT(Withholdong Tax commonly renamed to CIS. If this is true then a deduction needs to be applied to invoices for this customer.
WHTRate	Numeric	Withholding tax(also known as CIS) Rate
WHTReferences	String	Key Values pair of Withholding Tax(also known as CIS) Reference fields
OutstandingBalance	Numeric	Total amount of unpaid and overdue invoices
PaymentTerms	Object	This object contains information related to terms of payment like Days and Type
IsGoCardlessMandateSet	Boolean	This is a read only field which specifies whether the customer has set GoCardless mandate so that invoice payments can be taken through cardless payments for this customer
AverageDaysToPay	Numeric	Average Days taken by the customer to make the payment for his invoices.
CreateCustomerCodeIfDuplicate	Boolean	If this flag is true, create a new customer when customer code is duplicate
CreateCustomerNameIfEmptyOrNull	Boolean	If this flag is true, create a new customer when customer name is null or empty
PaymentTerms
Days	Numeric	Indicates payment terms in number of days. Invoice due date calculation is done based on this value.
Type	String	[AfterIssuedDate \| AfterMonthEnd] If value is AfterIssuedDate then number of days set above will be added to the invoice date in order to calculate the default invoice due date. If value is AfterMonthEnd then the days set above will be added to the end of the month in which the invoice is dated.
EnvelopeUrl	String	Customer’s envelope url.
PDFThemeId	String	Customer’s pdf theme id.

GET Operation

Retrives list of customers or single customer with details.

To get paginated customers list –
URL : /customers?page={page}&perpage={perpage}&sortby={sortyby}&order={order}&namestartswith={namestartswith}&filterarchived={filterarchived}

Request Parameters

Name	Description
page	Is the page number to be retrieved and the default value is 1.
perpage	The number of records to be returned and the default value is 10. Maximum allowed records per page is 100.
sortby	Sort by particular field. Available options are Code, Name, TotalPaidAmount, OutstandingBalance.
order	The sort direction and the default value is ‘Asc’ for ascending. Results can also be sorted in ‘Desc’ – descending order.
namestartswith	All customers with name starting from the specified value will be returned. Specify ‘non-alpha’ in order to retrieve all customers with name starting with numeric, special or foreign characters.
filterarchived	Flag to indicate if archived customers are to be fetched. True indicates archived customers will not be fetched. Default value is False.
When all the above parameters are excluded from the url, the first 10 quotes sorted by quote number in ascending order are returned.

Example response for page wise retrieval of customers


{
    "Data": [{
        "Addresses": null,
        "ApplyWHT": false,
        "AutoIncludeVATNumber": false,
        "AutomaticCreditControlEnabled": null,
        "AverageDaysToPay": 5,
        "Code": "BALA01",
        "Contacts": [{
            "Email": "[email protected]",
            "Fax": null,
            "Firstname": null,
            "LastName": null,
            "Mobile": null,
            "Name": null,
            "Telephone": null,
            "Title": null,
            "Website": ""
        }],
        "CreatedDate": null,
        "Currency": {
            "Code": "EUR",
            "DisplaySymbolOnRight": false,
            "ExchangeRate": 1.0000,
            "Name": "Euros",
            "Symbol": "€"
        },
        "CustomCheckBoxes": null,
        "CustomTextBoxes": null,
        "DefaultCustomerReference": null,
        "DefaultNominalCode": 4905,
        "DeliveryAddresses": null,
        "DiscountRate": 0,
        "DisplayName": "",
        "EmailTemplateNumber": 0,
        "FirstInvoiceDate": null,
        "Id": 7925606,
        "InvoiceCount": 0,
        "InvoiceFileFormat": null,
        "InvoicedNetAmount": 0,
        "InvoicedVATAmount": 0,
        "IsArchived": false,
        "IsGoCardlessMandateSet": false,
        "IsRegisteredInEC": false,
        "IsRegisteredOutsideEC": false,
        "LastInvoiceDate": null,
        "LastUpdatedDate": null,
        "Name": "Balazs Holenda",
        "Note": null,
        "OutstandingBalance": 0.0000,
        "OverrideInvoiceFileFormat": false,
        "PaymentTerms": {
            "Days": 0,
            "Type": "AfterIssuedDate"
        }, 
        "ReceivesWholesalePricing": false,
        "ShowDiscount": false,
        "Source": 0,
        "TotalPaidAmount": 120.8700,
        "UniqueEntityNumber": null,
        "UseCustomDeliveryAddress": false,
        "VATNumber": "",
        "WHTRate": 0,
        "WHTReferences": null
    }, {
        "Addresses": null,
        "ApplyWHT": false,
        "AutoIncludeVATNumber": false,
        "AutomaticCreditControlEnabled": null,
        "AverageDaysToPay": 0,
        "Code": "BALA02",
        "Contacts": [{
            "Email": "[email protected]",
            "Fax": null,
            "Firstname": null,
            "LastName": null,
            "Mobile": null,
            "Name": null,
            "Telephone": null,
            "Title": null,
            "Website": ""
        }],
        "CreatedDate": null,
        "Currency": {
            "Code": "EUR",
            "DisplaySymbolOnRight": false,
            "ExchangeRate": 1.0000,
            "Name": "Euros",
            "Symbol": "€"
        },
        "CustomCheckBoxes": null,
        "CustomTextBoxes": null,
        "DefaultCustomerReference": null,
        "DefaultNominalCode": 4905,
        "DeliveryAddresses": null,
        "DiscountRate": 0,
        "DisplayName": "",
        "EmailTemplateNumber": 0,
        "FirstInvoiceDate": null,
        "Id": 12469289,
        "InvoiceCount": 0,
        "InvoiceFileFormat": null,
        "InvoicedNetAmount": 0,
        "InvoicedVATAmount": 0,
        "IsArchived": false,
        "IsGoCardlessMandateSet": false,
        "IsRegisteredInEC": false,
        "IsRegisteredOutsideEC": false,
        "LastInvoiceDate": null,
        "LastUpdatedDate": null,
        "Name": "Balazs Holenda",
        "Note": null,
        "OutstandingBalance": 0.0000,
        "OverrideInvoiceFileFormat": false,
        "PaymentTerms": {
            "Days": 30,
            "Type": "AfterIssuedDate"
        },
        "ReceivesWholesalePricing": false,
        "ShowDiscount": false,
        "Source": 0,
        "TotalPaidAmount": 0.0000,
        "UniqueEntityNumber": null,
        "UseCustomDeliveryAddress": false,
        "VATNumber": "",
        "WHTRate": 0,
        "WHTReferences": null,
        "CreateCustomerCodeIfDuplicate" : false,  
        "CreateCustomerNameIfEmptyOrNull" : false,
    }],
    "MetaData": {
        "FirstPageUrl": "\/v2\/customers?page=1&perpage=2&sortby=Code&order=Asc&filterbystartcharacter=b&filterarchived=False",
        "LastPageUrl": "\/v2\/customers?page=18&perpage=2&sortby=Code&order=Asc&filterbystartcharacter=b&filterarchived=False",
        "NextPageUrl": "\/v2\/customers?page=2&perpage=2&sortby=Code&order=Asc&filterbystartcharacter=b&filterarchived=False",
        "PreviousPageUrl": null,
        "TotalRecords": 35
    }
}

To get details of a particular customer with all details –

URL : /customers/{code}

Example response for GET of customer


{
    "ApplyWHT": true,
    "AutoIncludeVATNumber": false,
    "AverageDaysToPay": 83,
    "Code": "PDRI91",
    "Contacts": [{
            "Email": "[email protected]",
            "Fax": null,
            "Firstname": null,
            "LastName": null,
            "Mobile": null,
            "Name": null,
            "Telephone": null,
            "Title": null,
            "Website": ""
    }],
    "CreatedDate": "2013-02-05 12:00:00 +05:30",
    "Currency": {
        "Code": "GBP",
        "ExchangeRate": 1.0000,
        "DisplayOnRight": false,
        "Name": "British Pounds",
        "Symbol": "£"
    },
    "CustomCheckBoxes": [{
        "Name": "FirstCheckbox",
        "Value": "1"
    }, {
        "Name": "SecondCheckbox",
        "Value": "1"
    }, {
        "Name": "ThirdCheckBox",
        "Value": "1"
    }],
    "CustomTextBoxes": [{
        "Name": "FirstName",
        "Value": "kjhkjh"
    }, {
        "Name": "LastName",
        "Value": "kjhkjh"
    }],
    "Addresses": [{
        "Line1": "1 Ashwood Close",
        "Line2": "Branton",
        "Line3": "Doncaster, South Yorkshire",
        "Line4": "GB",
        "PostCode": "DN3 3UB",
        "CountryCode": "GB",
        "CountryName": "United Kingdom",
    }],
    "DefaultNominalCode": 1,
    "DefaultCustomerReference": "",
    "DeliveryAddresses": [{
        "Line1": "1 Ashwood Close",
        "Line2": "Branton",
        "Line3": "Doncaster, South Yorkshire",
        "Line4": "GB",
        "PostCode": "DN3 3UB",
        "CountryCode": "GB",
        "CountryName": "United Kingdom",
    }],
    "DiscountRate": 0.0000,
    "DisplayName": "дравс дравс др, DN3 3UB",
    "IsRegisteredInEC": false,
    "Email": "",
    "EmailTemplateNumber": 6,
    "FaxNumber": "",
    "FirstInvoiceDate": "1900-01-01 12:00:00 +05:30",
    "UseCustomDeliveryAddress": true,
    "Id": 10535,
    "InvoiceCount": 0,
    "InvoiceFileFormat": "test",
    "InvoicedNetAmount": 0,
    "InvoicedVATAmount": 0,
    "IsArchived": false,
    "IsGoCardlessMandateSet": true,
    "ReceivesWholesalePricing": false,
    "Key": "a397a2e9-87f3-48ca-9bd0-1ad64585c0eb",
    "LastInvoiceDate": "1900-01-01 12:00:00 +05:30",
    "LastUpdatedDate": "2013-02-05 12:00:00 +05:30",
    "MobileNumber": "",
    "Name": "дравс дравс др",
    "Note": "test note",
    "OutstandingBalance": 0.0000,
    "IsRegisteredOutsideEC": false,
    "OverrideInvoiceFileFormat": true,
    "PaymentTerms": {
        "Days": 50,
        "Type": "AfterMonthEnd"
    },
    "CreateCustomerCodeIfDuplicate" : false,  
    "CreateCustomerNameIfEmptyOrNull" : false,
    "TotalPaidAmount": 0,
    "ShowDiscount": false,
    "Source": 43400,
    "TelephoneNumber": "",
    "UniqueEntityNumber": "",
    "VATNumber": "",
    "Website": "",
    "WHTRate": 12.0000,
    "WHTReferences": [{
        "Name": "UTR No",
        "Value": "321"
    }, {
        "Name": "Company Reg. Number",
        "Value": "333"
    }, {
        "Name": "NI number",
        "Value": "5555"
    }, {
        "Name": "Verification Number",
        "Value": "55533"
    }],
    "AutomaticCreditControlEnabled": false,
    "EnvelopeUrl": "/v2/documents/customers/c91b10ad-1ec8-40c8-8e8b-839fbbc3055b",
    "PDFThemeId": 456
}

POST Operation

Creates a new customer with the given customer data –

URL : /customers

Example request for POST of customer

Customer can be created with its header details. Customer code is auto generated if left blank. The auto generated code is constructed by appending the next available number( with a “0” at the left) to the first 4 characters of customer name.

If AutomaticCreditControlEnabled field is not specified, it will be set according to user’s settings. If automatic credit control and default setting for customer is enabled, automatic credit control will be enabled for newly created customer.


{
    "ApplyWHT": true,
    "AutoIncludeVATNumber": false,
    "Code": "PDRI91",
    "Contacts": [{
            "Email": "[email protected]",
            "Fax": null,
            "Firstname": null,
            "LastName": null,
            "Mobile": null,
            "Name": null,
            "Telephone": null,
            "Title": null,
            "Website": ""
    }],
    "CreatedDate": "2013-02-05 12:00:00 +05:30",
    "Currency": {
        "Code": "GBP",
        "ExchangeRate": 1.0000,
        "DisplayOnRight": false,
        "Name": "British Pounds",
        "Symbol": "£"
    },
    "CustomCheckBoxes": [{
        "Name": "FirstCheckbox",
        "Value": "1"
    }, {
        "Name": "SecondCheckbox",
        "Value": "1"
    }, {
        "Name": "ThirdCheckBox",
        "Value": "1"
    }],
    "CustomTextBoxes": [{
        "Name": "FirstName",
        "Value": "kjhkjh"
    }, {
        "Name": "LastName",
        "Value": "kjhkjh"
    }],
    "Addresses": [{
        "Line1": "1 Ashwood Close",
        "Line2": "Branton",
        "Line3": "Doncaster, South Yorkshire",
        "Line4": "GB",
        "PostCode": "DN3 3UB",
        "CountryCode": "GB",
    }],
    "DefaultNominalCode": 1,
    "DefaultCustomerReference": "",
    "DeliveryAddresses": [{
        "Line1": "1 Ashwood Close",
        "Line2": "Branton",
        "Line3": "Doncaster, South Yorkshire",
        "Line4": "GB",
        "PostCode": "DN3 3UB",
        "CountryCode": "GB",
    }] ,
    "DiscountRate": 0.0000,
    "DisplayName": "дравс дравс др, DN3 3UB",
    "IsRegisteredInEC": false,
    "Email": "",
    "EmailTemplateNumber": 3,
    "FaxNumber": "",
    "FirstInvoiceDate": "1900-01-01 12:00:00 +05:30",
    "UseCustomDeliveryAddress": true,
    "Id": 10535,
    "InvoiceCount": 0,
    "InvoiceFileFormat": "test",
    "InvoicedNetAmount": 0,
    "InvoicedVATAmount": 0,
    "IsArchived": false,
    "ReceivesWholesalePricing": false,
    "LastInvoiceDate": "1900-01-01 12:00:00 +05:30",
    "LastUpdatedDate": "2013-02-05 12:00:00 +05:30",
    "MobileNumber": "",
    "Name": "дравс дравс др",
    "Note": "test note",
    "OutstandingBalance": 0.0000,
    "IsRegisteredOutsideEC": false,
    "OverrideInvoiceFileFormat": true,
    "PaymentTerms": {
        "Days": 50,
        "Type": "AfterMonthEnd"
    },
    "CreateCustomerCodeIfDuplicate" : false,  
    "CreateCustomerNameIfEmptyOrNull" : false,
    "TotalPaidAmount": 0,
    "ShowDiscount": false,
    "Source": 43400,
    "TelephoneNumber": "",
    "UniqueEntityNumber": "",
    "VATNumber": "",
    "Website": "",
    "WHTRate": 12.0000,
    "WHTReferences": [{
        "Name": "UTR No",
        "Value": "321"
    }, {
        "Name": "Company Reg. Number",
        "Value": "333"
    }, {
        "Name": "NI number",
        "Value": "5555"
    }, {
        "Name": "Verification Number",
        "Value": "55533"
    }],
    "AutomaticCreditControlEnabled": false
}

To get customer code for specified customer name.

The name should be at least 2 characters in length.
The name can be a combination of alphabets, numbers and special characters.

URL : /customers/suggestedcode

Example request for POST of customer code


  {"Name":"Phil"}

Example response for POST of customer code


  "Phil01"

PUT Operation

Updates customer details for the code specified –

URL : /customers/{code}

Example request for PUT of customer

To update customer details you need to send the whole customer object (similar to the get customer response) and only update the required elements .

Unlike POST request, if AutomaticCreditControlEnabled field is not specified it will be set to false.


{
    "ApplyWHT": true,
    "AutoIncludeVATNumber": false,
    "Code": "PDRI91",
    "Contacts": [{
            "Email": "[email protected]",
            "Fax": null,
            "Firstname": null,
            "LastName": null,
            "Mobile": null,
            "Name": null,
            "Telephone": null,
            "Title": null,
            "Website": ""
    }],
    "CreatedDate": "2013-02-05 12:00:00 +05:30",
    "Currency": {
        "Code": "GBP",
        "ExchangeRate": 1.0000,
        "DisplayOnRight": false,
        "Name": "British Pounds",
        "Symbol": "£"
    },
    "CustomCheckBoxes": [{
        "Name": "FirstCheckbox",
        "Value": "1"
    }, {
        "Name": "SecondCheckbox",
        "Value": "1"
    }, {
        "Name": "ThirdCheckBox",
        "Value": "1"
    }],
    "CustomTextBoxes": [{
        "Name": "FirstName",
        "Value": "kjhkjh"
    }, {
        "Name": "LastName",
        "Value": "kjhkjh"
    }],
    "Addresses": [{
        "Line1": "1 Ashwood Close",
        "Line2": "Branton",
        "Line3": "Doncaster, South Yorkshire",
        "Line4": "GB",
        "PostCode": "DN3 3UB",
        "CountryCode": "GB"
    }],
    "DefaultNominalCode": 1,
    "DefaultCustomerReference": "",
    "DeliveryAddresses": [{
        "Line1": "1 Ashwood Close",
        "Line2": "Branton",
        "Line3": "Doncaster, South Yorkshire",
        "Line4": "GB",
        "PostCode": "DN3 3UB",
        "CountryCode": "GB"
    }],
    "DiscountRate": 0.0000,
    "DisplayName": "дравс дравс др, DN3 3UB",
    "IsRegisteredInEC": false,
    "Email": "",
    "EmailTemplateNumber": 1,
    "FaxNumber": "",
    "FirstInvoiceDate": "1900-01-01 12:00:00 +05:30",
    "UseCustomDeliveryAddress": true,
    "Id": 10535,
    "InvoiceCount": 0,
    "InvoiceFileFormat": "test",
    "InvoicedNetAmount": 0,
    "InvoicedVATAmount": 0,
    "IsArchived": false,
    "ReceivesWholesalePricing": false,
    "LastInvoiceDate": "1900-01-01 12:00:00 +05:30",
    "LastUpdatedDate": "2013-02-05 12:00:00 +05:30",
    "MobileNumber": "",
    "Name": "дравс дравс др",
    "Note": "test note",
    "OutstandingBalance": 0.0000,
    "IsRegisteredOutsideEC": false,
    "OverrideInvoiceFileFormat": true,
    "PaymentTerms": {
        "Days": 50,
        "Type": "AfterMonthEnd"
     },
    "CreateCustomerCodeIfDuplicate" : false,  
    "CreateCustomerNameIfEmptyOrNull" : false,
    "TotalPaidAmount": 0,
    "ShowDiscount": false,
    "Source": 43400,
    "TelephoneNumber": "",
    "UniqueEntityNumber": "",
    "VATNumber": "",
    "Website": "",
    "WHTRate": 12.0000,
    "WHTReferences": [{
        "Name": "UTR No",
        "Value": "321"
    }, {
        "Name": "Company Reg. Number",
        "Value": "333"
    }, {
        "Name": "NI number",
        "Value": "5555"
    }, {
        "Name": "Verification Number",
        "Value": "55533"
    }],
    "AutomaticCreditControlEnabled": false
}

DELETE Operation

Deletes the details of the specified customer code in the URL

URL : /customers/{code}

Customers

URL:

Method(s):

Response Formats:

Description:

Parameters

GET Operation

Request Parameters

Example response for page wise retrieval of customers

Example response for GET of customer

POST Operation

Example request for POST of customer

Example request for POST of customer code

Example response for POST of customer code

PUT Operation

Example request for PUT of customer

DELETE Operation

In This Section

REST API Methods

Supplementary Functions

Bank

Customers

Purchases

Invoices