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
| Name | Type | Description |
|---|---|---|
| Number | Numeric | Number given to quote |
| Date | Date | Date on which quote is issued. For e.g. [JSONDATE] |
| CustomerCode | String | Unique customer code of quote’s customer |
| CustomerName | String | Quote’s customer name |
| CustomerReference | String | Quote’s reference |
| GrossAmount | Numeric | Gross amount |
| NetAmount | Numeric | Quote amount excluding VAT |
| VATAmount | Numeric | Vat applied to quote |
| Category | Object | Category related information |
| Currency | Object | Currency related information with default exchange rate or quote specific exchange rate specified by user. |
| LineItems | Collection | Collection of line items |
| ProjectNumber | Numeric | Project number of the quote’s associated project |
| SuppressAmount | Boolean | Flag Indicating if total of quote to be displayed |
| PreviousNumber | Numeric | Quote number of previous quote |
| NextNumber | Numeric | Quote number of next quote |
| Permalink | String | Permanent url of quote document that can be shared. |
| LineItem parameters | ||
| Number | Numeric | This 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. |
| Quantity | Numeric | Units of line item |
| Description | String | Description for a line item |
| HomeCurrencyRate | Numeric | Rate of the line item in home currency. |
| VATLevel | Numeric | VAT 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. |
| HomeCurrencyVATAmount | Numeric | Custom 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. |
| VATExempt | Boolean | Whether vat is exempted or not for a line item. |
| NominalCode | Numeric | Nominal Code maps to code property of nominal resource |
| TaxCode | String | Tax code used for users with singapore dollars set as home currency. |
| ProductCode | String | ProductCode 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. |
| ProductName | String | Name of the product |
| Rate | Numeric | The rate in quote currency |
| VATAmount | Numeric | The 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
| 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. |
| sortby | The 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 |
| order | The sort direction and the default value is ‘Asc’ for ascending. Results can also be sorted in ‘Desc’ – descending order. |
| customercode | Retrieve 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}