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

NameTypeDescription
CodeStringUnique code used to represent a customer
DisplayNameStringCustomer name formatted according to user setting
NameStringCustomer’s name
SourceNumericSource
CreatedDateDateDate of customer creation. For e.g. [JSONDATE]
LastUpdatedDateDateLast date when customer was updated. For e.g. [JSONDATE]
IsRegisteredInECBooleanFlag indicating whether customer is from european country or not .
IsRegisteredOutsideECBooleanFlag indicates whether customer is from outside European country.
NoteStringNote
DiscountRateNumericDiscount (in percentage, 0-100 value) applied when a new invoice created for this customer.
ShowDiscountBooleanFlag indicating whether to show discount on Invoice or not
VatNumberStringVat number of the customer
AutoIncludeVATNumberBooleanFlag 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.
TotalPaidAmountNumericTotal amount paid.
InvoicedNetAmountNumericInvoice net amount for customer.
InvoicedVATAmountNumericInvoice VAT amount for customer.
UseCustomDeliveryAddressBooleanFlag indicating whether user has a delivery address or not.
ReceivesWholesalePricingBooleanFlag indicating whether to receive discount in pricing. This is relevant when using autocomplete fields of a nominal code.
DefaultNominalCodeNumericDefault Charge type is the default sales type with which invoice for this customer is created
IsArchivedBooleanFlag indicating whether user is archived or not.
InvoiceCountNumericThe total number of invoices ever raised for this customer.
CurrencyObjectCurrency related information including code, name and symbol
DefaultCustomerReferenceStringDefault customer reference
EmailTemplateNumberNumericThe default email template to use when emailing invoices to this customer
OverrideInvoiceFileFormatBooleanFlag indicationg whether or not to override the account default setting for the filename given to PDFs when producing an invoice
InvoiceFileFormatStringInvoice file format
FirstInvoiceDateDateThe date of the first invoice for this customer. For e.g. [JSONDATE]
LastInvoiceDateDateThe date of the last invoice for this customer. For e.g. [JSONDATE]
UniqueEntityNumberStringUnique 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
AutomaticCreditControlEnabledBooleanFlag indicating whether automatic credit control is enabled or not
ContactsObjectThis object contains an array of customers contact information like Telephone, FAX, Mobile, Website
AddressesObjectThis object contains customer address information like Line1, Line2, Line3, Line4, postCode, CountryCode and CountryName
DeliveryAddressesObjectCustomer delivery address information like name, Line1, Line2, Line3, Line4, postCode, CountryCode and CountryName
CustomTextBoxesCollectionCollection 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.
CustomCheckBoxesCollectionCollection 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
ApplyWHTBooleanWHT(Withholdong Tax commonly renamed to CIS. If this is true then a deduction needs to be applied to invoices for this customer.
WHTRateNumericWithholding tax(also known as CIS) Rate
WHTReferencesStringKey Values pair of Withholding Tax(also known as CIS) Reference fields
OutstandingBalanceNumericTotal amount of unpaid and overdue invoices
PaymentTermsObjectThis object contains information related to terms of payment like Days and Type
IsGoCardlessMandateSetBooleanThis 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
AverageDaysToPayNumericAverage Days taken by the customer to make the payment for his invoices.
CreateCustomerCodeIfDuplicateBooleanIf this flag is true, create a new customer when customer code is duplicate
CreateCustomerNameIfEmptyOrNullBooleanIf this flag is true, create a new customer when customer name is null or empty
PaymentTerms
DaysNumericIndicates payment terms in number of days. Invoice due date calculation is done based on this value.
TypeString[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.
EnvelopeUrlStringCustomer’s envelope url.
PDFThemeIdStringCustomer’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

NameDescription
pageIs the page number to be retrieved and the default value is 1.
perpageThe number of records to be returned and the default value is 10. Maximum allowed records per page is 100.
sortbySort by particular field. Available options are Code, Name, TotalPaidAmount, OutstandingBalance.
orderThe sort direction and the default value is ‘Asc’ for ascending. Results can also be sorted in ‘Desc’ – descending order.
namestartswithAll 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.
filterarchivedFlag 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": "test@testtrick.com",
            "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": "test@testtrick.com",
            "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": "test@testtrick.com",
            "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": "test@testtrick.com",
            "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": "test@testtrick.com",
            "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}

See how KashFlow works with your business and your books