Quotes

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/quotes

Method(s):

get,post,put,delete

Response Formats:

JSON, XML

Description:

These methods allow you to retrieve, create, update and delete quotes. The individual resource is identified by the quote number. So /quotes/123 would return the quote with number 123. Similarly a PUT to that URL would update quote 123. A GET to /quotes will return all quotes.

Parameters

NameTypeDescription
NumberNumericNumber given to quote
DateDateDate on which quote is issued. For e.g. [JSONDATE]
CustomerCodeStringUnique customer code of quote’s customer
CustomerNameStringQuote’s customer name
CustomerReferenceStringQuote’s reference
GrossAmountNumericGross amount
NetAmountNumericQuote amount excluding VAT
VATAmountNumericVat applied to quote
CategoryObjectCategory related information
CurrencyObjectCurrency related information with default exchange rate or quote specific exchange rate specified by user.
LineItemsCollectionCollection of line items
ProjectNumberNumericProject number of the quote’s associated project
SuppressAmountBooleanFlag Indicating if total of quote to be displayed
PreviousNumberNumericQuote number of previous quote
NextNumberNumericQuote number of next quote
PermalinkStringPermanent url of quote document that can be shared.
LineItem parameters
NumberNumericThis field serves 2 purposes:
1. It uniquely identifies a line item.
2. It represents the sort order, i.e., items can be displayed in the line items list in the same order (Ascending) as their line number.
Note : Though line number uniquely identifies a line, but it may change when sort order is altered. Also, it should be set to 0 for new line item.
QuantityNumericUnits of line item
DescriptionStringDescription for a line item
HomeCurrencyRateNumericRate of the line item in home currency.
VATLevelNumericVAT rate for line item. For PUT and POST request, It can not be specified in case of VATExempt property as true. This field is readonly.
HomeCurrencyVATAmountNumericCustom VAT amount of the invoice line in home currency. For PUT and POST request, If specifying with some value in case of VATExempt property as true, the value will be ignored and will be treated as 0.
VATExemptBooleanWhether vat is exempted or not for a line item.
NominalCodeNumericNominal Code maps to code property of nominal resource
TaxCodeStringTax code used for users with singapore dollars set as home currency.
ProductCodeStringProductCode for one of the products configured for the Nominal/SalesType specified in NominalCode property of this resource should be specified in case of PUT/POST and will be returned in case of GET. The value of this property maps to Code property of product resource.
ProductNameStringName of the product
RateNumericThe rate in quote currency
VATAmountNumericThe VAT amount in quote currency

GET Operation

Returns the details of the one or all quotes according to the URL specified. To get list of quotes –

URL : /quotes

A list of quotes is returned (ordered by quote number in ascending order). To make the response compact, we only return the summary of each quote with required fields. Also to avoid overwhelming the server or the network with a large result sets, we return only the first 10 quotes sorted by quote number in ascending order, instead of returning the entire quotes list. To retrieve a larger result set of quotes the pagination URL below can be used.

Example response for GET of quotes


{
    "Data": [{
        "Category": {
            "IconColor": null,
            "IconId": 0,
            "Name": " - ",
            "Number": 0,
            "IconType": null
        },
        "Currency": null,
        "CustomerCode": "BRIA01      ",
        "CustomerId": 6657,
        "CustomerName": "Brian Hayes, 2541",
        "Date": "2012-06-21 12:00:00 +05:30",
        "GrossAmount": 0.6500,
        "Id": 67023,
        "LineItems": null,
        "NetAmount": 0.5400,
        "NextNumber": null,
        "Number": 5,
        "PreviousNumber": null,
        "ProjectNumber": 0,
        "CustomerReference": "",
        "SuppressAmount": false,
        "VATAmount": 0.1100
    }, {
        "Category": {
            "IconColor": null,
            "IconId": 0,
            "Name": " - ",
            "Number": 0,
            "IconType": null
        },
        "Currency": null,
        "CustomerCode": "BRIA01      ",
        "CustomerId": 6657,
        "CustomerName": "Brian Hayes, 2541",
        "Date": "2013-02-07 12:00:00 +05:30",
        "GrossAmount": 0.0000,
        "Id": 67344,
        "LineItems": null,
        "NetAmount": 0.0000,
        "NextNumber": null,
        "Number": 5675,
        "PreviousNumber": null,
        "ProjectNumber": 0,
        "CustomerReference": "TestReference",
        "SuppressAmount": false,
        "VATAmount": 0.0000
    }, {
        "Category": {
            "IconColor": null,
            "IconId": 0,
            "Name": " - ",
            "Number": 0,
            "IconType": null
        },
        "Currency": null,
        "CustomerCode": "TARA01      ",
        "CustomerId": 6974,
        "CustomerName": "Tara Cleary, TQ12 4EH",
        "Date": "2012-12-19 12:00:00 +05:30",
        "GrossAmount": 0.0000,
        "Id": 67290,
        "LineItems": null,
        "NetAmount": 0.0000,
        "NextNumber": null,
        "Number": 65436,
        "PreviousNumber": null,
        "ProjectNumber": 0,
        "CustomerReference": "fg45",
        "SuppressAmount": false,
        "VATAmount": 0.0000
    }, {
        "Category": {
            "IconColor": null,
            "IconId": 0,
            "Name": " - ",
            "Number": 0,
            "IconType": null
        },
        "Currency": null,
        "CustomerCode": "BRIA01      ",
        "CustomerId": 6657,
        "CustomerName": "Brian Hayes, 2541",
        "Date": "2013-02-07 12:00:00 +05:30",
        "GrossAmount": 0.0000,
        "Id": 67346,
        "LineItems": null,
        "NetAmount": 0.0000,
        "NextNumber": null,
        "Number": 78565,
        "PreviousNumber": null,
        "ProjectNumber": 0,
        "CustomerReference": "TestReference",
        "SuppressAmount": false,
        "VATAmount": 0.0000
    }],
    "MetaData": {
        "FirstPageUrl": "http://securedwebapp.com/cpt_rest_api/quotes?page=1&perpage=10&sortby=Number&order=Asc",
        "LastPageUrl": "http://securedwebapp.com/cpt_rest_api/quotes?page=3&perpage=10&sortby=Number&order=Asc",
        "NextPageUrl": "http://securedwebapp.com/cpt_rest_api/quotes?page=2&perpage=10&sortby=Number&order=Asc",
        "PreviousPageUrl": null,
        "TotalRecords": 29
    }
}

To get details of particular quote with the specified number –

URL : /quotes/{number}

{number} in the URL should be replaced with the number of the quote to be retrieved.

Exchange Rate specified in “Currency” section can be the default currency rate or it can be user specified currency rate for that particular quote.

Example response for GET of quote


{
    "Category": {
        "IconColor": null,
        "IconId": 0,
        "Name": null,
        "Number": 0,
        "IconType": null
    },
    "Currency": {
        "Code": "INR",
        "ExchangeRate": 50.0000,
        "DisplaySymbolOnRight": false,
        "Name": "Indian Rupees",
        "Symbol": "Rs"
    },
    "CustomerCode": "13",
    "CustomerId": 7343,
    "CustomerName": "Jack Turner",
    "Date": "2012-03-01 12:00:00",
    "GrossAmount": 120.0000,
    "Id": 67295,
    "LineItems": [{
        "NominalCode": 1,
        "Description": "Adding a 3rd Line Item",
        "Number": 1,
        "ProductCode": "510",
        "ProductName": "Mobile",
        "Quantity": 10.0000,
        "HomeCurrencyRate": 10.0000,
        "HomeCurrencyVATAmount": 20.0000,
        "VATExempt": false,
        "VATLevel": 20.0000,
        "TaxCode": "",
        "Rate":500,
        "VATAmount" : 1000
    }],
    "NetAmount": 100.0000,
    "NextNumber": 11248,
    "Number": 11,
    "PreviousNumber": 11247,
    "ProjectNumber": 0,
    "CustomerReference": "dgrsfgsrf",
    "SuppressAmount": false,
    "VATAmount": 20.0000,
    "Permalink": "/v2/documents/quote/c4093bc7-b70c-435d-ac70-d9cd2f478a54"
}

To get paginated quotes list –

URL : /quotes?page={page}&perpage={perpage}&sortby={sortby}&order={order}&customercode={customercode}

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.
sortbyThe column to sort the results by and the default value is ‘Number’. Below is a list of sort by values :
Number,
CategoryName,
Reference,
CustomerName,
Date,
NetAmount
orderThe sort direction and the default value is ‘Asc’ for ascending. Results can also be sorted in ‘Desc’ – descending order.
customercodeRetrieve quotes for a particular customer. You don’t need to specify it, if you don’t want the quote list to be filtered by customer code.
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 quotes


{
    "Data": [{
        "Category": {
            "IconColor": null,
            "IconId": 0,
            "Name": " - ",
            "Number": 0,
            "IconType": null
        },
        "Currency": null,
        "CustomerCode": "13",
        "CustomerId": 7343,
        "CustomerName": "Jack Turner",
        "Date": "2012-03-01 12:00:00",
        "ExchangeRate": 0,
        "GrossAmount": 120.0000,
        "Id": 67295,
        "LineItems": null,
        "NetAmount": 100.0000,
        "NextNumber": null,
        "Number": 11,
        "PreviouseNumber": null,
        "ProjectNumber": 0,
        "CustomerReference": "dgrsfgsrf",
        "SuppressAmount": false,
        "VATAmount": 20.0000
    }, {
        "Category": {
            "IconColor": null,
            "IconId": 0,
            "Name": " - ",
            "Number": 0,
            "IconType": null
        },
        "Currency": null,
        "CustomerCode": "13",
        "CustomerId": 7343,
        "CustomerName": "Jack Turner",
        "Date": "2012-10-09 12:00:00",
        "ExchangeRate": 0,
        "GrossAmount": 240.0000,
        "Id": 67311,
        "LineItems": null,
        "NetAmount": 200.0000,
        "NextNumber": null,
        "Number": 67,
        "PreviouseNumber": null,
        "ProjectNumber": 0,
        "CustomerReference": "dgrsfgsrf",
        "SuppressAmount": false,
        "VATAmount": 40.0000
    }, {
        "Category": {
            "IconColor": null,
            "IconId": 0,
            "Name": " - ",
            "Number": 0,
            "IconType": null
        },
        "Currency": null,
        "CustomerCode": "04",
        "CustomerId": 7329,
        "CustomerName": "Jack Sparrow",
        "Date": "2012-08-17 12:00:00",
        "ExchangeRate": 0,
        "GrossAmount": 264.4600,
        "Id": 67045,
        "LineItems": null,
        "NetAmount": 212.8800,
        "NextNumber": null,
        "Number": 138,
        "PreviousNumber": null,
        "ProjectNumber": 0,
        "CustomerReference": "This is a Quote",
        "SuppressAmount": false,
        "VATAmount": 51.5800
    }, {
        "Category": {
            "IconColor": null,
            "IconId": 0,
            "Name": " - ",
            "Number": 0,
            "IconType": null
        },
        "Currency": null,
        "CustomerCode": "DJNF01",
        "CustomerId": 6673,
        "CustomerName": "djnfc",
        "Date": "2012-03-22 12:00:00",
        "ExchangeRate": 0,
        "GrossAmount": 120.0000,
        "Id": 67055,
        "LineItems": null,
        "NetAmount": 100.0000,
        "NextNumber": null,
        "Number": 145,
        "PreviousNumber": null,
        "ProjectNumber": 0,
        "CustomerReference": "This is a Quote",
        "SuppressAmount": false,
        "VATAmount": 20.0000
    }, {
        "Category": {
            "IconColor": null,
            "IconId": 0,
            "Name": " - ",
            "Number": 0,
            "IconType": null
        },
        "Currency": null,
        "CustomerCode": "04",
        "CustomerId": 7329,
        "CustomerName": "Jack Sparrow",
        "Date": "2012-09-04 12:00:00",
        "ExchangeRate": 0,
        "GrossAmount": 0.0000,
        "Id": 67060,
        "LineItems": null,
        "NetAmount": 0.0000,
        "NextNumber": null,
        "Number": 148,
        "PreviousNumber": null,
        "ProjectNumber": 0,
        "CustomerReference": "",
        "SuppressAmount": false,
        "VATAmount": 0.0000
    }, {
        "Category": {
            "IconColor": null,
            "IconId": 0,
            "Name": " - ",
            "Number": 0,
            "IconType": null
        },
        "Currency": null,
        "CustomerCode": "04",
        "CustomerId": 7329,
        "CustomerName": "Jack Sparrow",
        "Date": "2012-09-05 12:00:00",
        "ExchangeRate": 0,
        "GrossAmount": 0.0000,
        "Id": 67061,
        "LineItems": null,
        "NetAmount": 0.0000,
        "NextNumber": null,
        "Number": 149,
        "PreviousNumber": null,
        "ProjectNumber": 0,
        "CustomerReference": "",
        "SuppressAmount": false,
        "VATAmount": 0.0000
    }, {
        "Category": {
            "IconColor": null,
            "IconId": 0,
            "Name": " - ",
            "Number": 0,
            "IconType": null
        },
        "Currency": null,
        "CustomerCode": "04",
        "CustomerId": 7329,
        "CustomerName": "Jack Sparrow",
        "Date": "2012-09-05 12:00:00",
        "ExchangeRate": 0,
        "GrossAmount": 0.0000,
        "Id": 67062,
        "LineItems": null,
        "NetAmount": 0.0000,
        "NextNumber": null,
        "Number": 150,
        "PreviousNumber": null,
        "ProjectNumber": 0,
        "CustomerReference": "",
        "SuppressAmount": false,
        "VATAmount": 0.0000
    }, {
        "Category": {
            "IconColor": null,
            "IconId": 0,
            "Name": " - ",
            "Number": 0,
            "IconType": null
        },
        "Currency": null,
        "CustomerCode": "04",
        "CustomerId": 7329,
        "CustomerName": "Jack Sparrow",
        "Date": "2012-09-05 12:00:00",
        "ExchangeRate": 0,
        "GrossAmount": 0.0000,
        "Id": 67063,
        "LineItems": null,
        "NetAmount": 0.0000,
        "NextNumber": null,
        "Number": 151,
        "PreviousNumber": null,
        "ProjectNumber": 0,
        "CustomerReference": "",
        "SuppressAmount": false,
        "VATAmount": 0.0000
    }, {
        "Category": {
            "IconColor": null,
            "IconId": 0,
            "Name": " - ",
            "Number": 0,
            "IconType": null
        },
        "Currency": null,
        "CustomerCode": "THUN01",
        "CustomerId": 7538,
        "CustomerName": "Thunderbird",
        "Date": "2012-09-05 12:00:00",
        "ExchangeRate": 0,
        "GrossAmount": 0.0000,
        "Id": 67064,
        "LineItems": null,
        "NetAmount": 0.0000,
        "NextNumber": null,
        "Number": 152,
        "PreviousNumber": null,
        "ProjectNumber": 0,
        "CustomerReference": "This is a Quote",
        "SuppressAmount": false,
        "VATAmount": 0.0000
    }, {
        "Category": {
            "IconColor": null,
            "IconId": 0,
            "Name": " - ",
            "Number": 0,
            "IconType": null
        },
        "Currency": null,
        "CustomerCode": "04",
        "CustomerId": 7329,
        "CustomerName": "Jack Sparrow",
        "Date": "2012-09-05 12:00:00",
        "ExchangeRate": 0,
        "GrossAmount": 2.4000,
        "Id": 67065,
        "LineItems": null,
        "NetAmount": 2.0000,
        "NextNumber": null,
        "Number": 153,
        "PreviousNumber": null,
        "ProjectNumber": 0,
        "CustomerReference": "",
        "SuppressAmount": false,
        "VATAmount": 0.4000
    }],
    "MetaData": {
        "FirstPageUrl": "http://securedwebapp.com/cpt_rest_api/quotes?page=1&perpage=10&sortby=Number&order=Asc",
        "LastPageUrl": "http://securedwebapp.com/cpt_rest_api/quotes?page=15&perpage=10&sortby=Number&order=Asc",
        "NextPageUrl": "http://securedwebapp.com/cpt_rest_api/quotes?page=2&perpage=10&sortby=Number&order=Asc",
        "PreviousPageUrl": null,
        "TotalRecords": 148
    }
}

POST Operation


Quote can be created with its header details. Only quote number is a required field, rest can be left blank. Line number should be set to 0.
Creates a new quote record with the given quote data using following URL –

URL : /quotes

Example request for POST of quote


{
    "Category": {
            "Number": 0,
            "IconType": "flag",
            "IconId": 0,
            "Name": " - ",
            "IconColor": "green"
    },
    "Currency": {
        "Code": "GBP",
        "ExchangeRate": 50.0000,
        "DisplaySymbolOnRight": false,
        "Name": "British Pounds",
        "Symbol": "£"
    },
    "CustomerCode": "BRIA01",
    "CustomerId": 6657,
    "CustomerName": "Brian Hayes",
    "Date": "2012-06-21 12:00:00 +05:30",
    "GrossAmount": 0.2200,
    "Id": 67343,
    "LineItems": [{
        "NominalCode": 1,
        "Description": "هذا هو نص اختبار",
        "Number": 0,
        "ProductCode": "",
        "Quantity": 3.0000,
        "HomeCurrencyRate": 12,
        "HomeCurrencyVATAmount": 5,
        "VATExempt": true,
        "VATLevel": 0,
        "TaxCode": "",
        "Rate":600,
        "VATAmount" : 250
    }],
    "NetAmount": 0.1800,
    "NextNumber": 5675,
    "Number": 9087,
    "PreviousNumber": 111111169,
    "ProjectNumber": 1,
    "CustomerReference": "test",
    "SuppressAmount": false,
    "VATAmount": 0.0400
}

PUT Operation

Updates quote details for the specified quote number using the following URL –

URL : /quotes/{number}

{number} in the URL should be replaced with the number of the quote to be updated. To update quote details you need to provide the whole quote object (similar to the GET quote response) and only update the required elements. Quote number is a mandatory field and if the number passed in the url and the request body are not same, then the quote number gets updated with the later (provided it is unique).

To create a new line item, item with a number 0 should be specified.
If existing line item(s) is/are not passed in PUT request body, then those line item(s) are deleted from DB.
In order to change sequence of line items just put the line items in the same order as desired. This will also update line numbers accordingly.

Example request for PUT of quote


{
    "Category": {
        "Number": 0,
            "IconType": "flag",
            "IconId": 0,
            "Name": " - ",
            "IconColor": "green"
    },
    "Currency": {
        "Code": "",
        "ExchangeRate": 50.0000,
        "Name": "Indian Rupees",
        "Symbol": "Rs",
        "DisplaySymbolOnRight": false
    },
    "CurrencyName": null,
    "CustomerCode": "13",
    "CustomerDiscount": 0.0000,
    "CustomerName": "Jack Turner",
    "Date": "2012-10-09 12:00:00 +05:30",
    "DefaultChargeType": 9998,
    "Ec": 0,
    "GrossAmount": 120.0000,
    "LineItems": [{
        "ApplyTax1": false,
        "ApplyTax2": false,
        "ApplyTax3": false,
        "ApplyTax4": false,
        "ApplyTax5": false,
        "NominalCode": 1,
        "Description": "Adding a 4rd Line Item",
        "ProductCode": "",
        "Quantity": 10.0000,
        "HomeCurrencyRate": 10.0000,
        "Tax1Amount": 0,
        "Tax2Amount": 0,
        "Tax3Amount": 0,
        "Tax4Amount": 0,
        "Tax5Amount": 0,
        "HomeCurrencyVATAmount": 20.0000,
        "VATExempt": false,
        "VATLevel": 20.0000,
        "TaxCode": "",
        "Rate":500,
        "VATAmount":1000

    }],
    "NetAmount": 100.0000,
    "NextNumber": 10,
    "Number": 9,
    "OutSideEc": 0,
    "PreviousNumber": 6,
    "ProjectNumber": 0,
    "CustomerReference": "dgrsfgsrf",
    "SuppressAmount": 0,
    "VATAmount": 20.0000,
    "VATNumber": "123"
}

DELETE Operation

Deletes the quote with the number provided in the URL –

URL : /quotes/{number}

See how KashFlow works with your business and your books