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/projects |
Method(s): | get,post,put,delete |
Response Formats: | JSON or XML |
Description: | These methods allow you to retrieve, create, update or delete projects. The individual resource is identified by the project number. So /projects/10 would return the project with number 10. Similarly a PUT to that URL would update project 10. |
Parameters
| Name | Type | Description |
|---|---|---|
| Number* | Numeric | Unique number given to the project |
| ActualJournalsAmount | Numeric | Balance of journals (Credit – Debit) associated with the project |
| ActualPurchasesAmount | Numeric | Total value of purchases against the project |
| ActualSalesAmount | Numeric | Sum of the amounts of all invoices associated with the project |
| CustomerId | Numeric | Id of the customer against whom the project has been created |
| CustomerName | String | Name of the customer against whom the project has been created |
| Description | String | Description of the project |
| StartDate | Date | Start date of the project For example: JSON : [JSONDATE], XML : [XMLDATE] |
| AssociatedQuotesCount | Numeric | Count of quotes created against the given project |
| ExcludeVAT | Numeric | Setting for whether VAT is to be excluded or not for the project |
| Name | String | Name of the project |
| Note | String | Notes belonging to the project |
| Reference | String | Reference text for the project |
| EndDate | Date | End date of the project. For example: JSON : [JSONDATE] XML : [XMLDATE] |
| Status | Numeric | Value which states whether the project is complete, active or archived. Value 0 = complete, 1 = active, 2 = archived |
| StatusName | String | Name of the project state (complete, active or archived) |
| TargetPurchasesAmount | Numeric | Value of purchases against the project |
| VatAmountBankTransactions | Numeric | Total VAT amount on bank transactions for the project |
| ActualSalesVATAmount | Numeric | Total VAT amount on sales against the project |
| TargetSalesAmount | Numeric | Value of sales against the project |
| ActualPurchasesVATAmount | Numeric | Total VAT amount on purchases against the project |
| WorkInProgressAmount | Numeric | The difference between the expected income( Target income prorata) and actual income at the current stage of the project. The current stage of the project is calculated using the ratio of the actual expenditure and the target expenditure. |
* Any parameters marked with an asterix are mandatory. All others are optional.
GET Operation
To get list of projects –URL : /projects?customerCode={customerCode}
The list of projects returned is ordered by project number in ascending order and displays only summary of each project (with limited fields only).
Request Parameters
| Name | Description |
|---|---|
| customerCode | Retrieve list of projects for a particular customer. It will also list archived projects of this customer. You don’t need to specify this parameter if you don’t want the project list to be filtered by customer code. |
Example response for GET of project list
[{
"ActualJournalsAmount":0,
"ActualPurchasesAmount":0,
"ActualSalesAmount":0,
"CustomerId":0,
"CustomerName":"",
"StartDate":"2012-09-10 12:00:00 +05:30",
"EndDate":"2012-09-13 12:00:00 +05:30",
"Description":"This is a Test Project",
"AssociatedQuotesCount":0,
"ExcludeVAT":0,
"Name":"Project1",
"Note":"This is a Test Project",
"Number":1,
"Reference":"",
"Status":1,
"StatusName":"Active",
"TargetPurchasesAmount":0,
"TargetSalesAmount":0,
"ActualPurchasesVATAmount":0,
"ActualSalesVATAmount":0
},
{
"ActualJournalsAmount":0,
"ActualPurchasesAmount":0,
"ActualSalesAmount":0,
"CustomerId":0,
"CustomerName":"",
"StartDate":"2012-10-10 12:00:00 +05:30",
"EndDate":"2012-11-10 12:00:00 +05:30/",
"Description":"This is a Test Project",
"AssociatedQuotesCount":0,
"ExcludeVAT":0,
"Name":"Project2",
"Note":"This is Test Project 2",
"Number":2,
"Reference":"",
"Status":1,
"StatusName":"Active",
"TargetPurchasesAmount":0,
"TargetSalesAmount":0,
"ActualPurchasesVATAmount":0,
"ActualSalesVATAmount":0
}
]
To get details of a particular project –
URL : /project/{number}
{number} in the URL should be replaced with the number of the project to be fetched.
It cannot be less than or equal to zero.
Example response for GET of project
{
"ActualJournalsAmount": 0.0000,
"ActualPurchasesAmount": 1200.0000,
"ActualSalesAmount": 0.0000,
"CustomerCode": "DARK01",
"CustomerName": "Dark Knight",
"Description": "Dark Knight Project",
"EndDate": "2012-10-10 12:00:00 +05:30",
"AssociatedQuotesCount": 13,
"ExcludeVAT": 0,
"Name": "Dark Knight Project 1",
"Note": "",
"Number": 4,
"Reference": "Dark Knight Reference",
"StartDate": "2012-10-09 12:00:00 +05:30",
"Status": 1, "StatusName":
"Active", "TargetPurchasesAmount": 800.0000,
"TargetSalesAmount": 1000.0000,
"ActualPurchasesVATAmount": 200.0000,
"ActualSalesVATAmount": 0.0000,
"WorkInProgressAmount": 1500.00000
}
POST Operation
Creates a new project with the given data using following URL –URL : /projects
Project can be created by specifying a unique project number in the request body. If project number is not provided, it is auto-generated by the system. The values for rest of the fields may or may not be provided.
Example request for POST of project
{
"ActualJournalsAmount":0,
"ActualPurchasesAmount":0,
"ActualSalesAmount":439,
"CustomerId":6657,
"CustomerName":"Brian Hayes",
"Description":"",
"StartDate":"2012-10-09 12:00:00 +05:30",
"EndDate":"2012-10-10 12:00:00 +05:30",
"AssociatedQuotesCount":6,
"ExcludeVAT":0,
"Name":"New Project Created",
"Note":"",
"Number":10,
"Reference":"test",
"Status":1,
"StatusName":"Active",
"TargetPurchasesAmount":0,
"TargetSalesAmount":100,
"ActualPurchasesVATAmount":0,
"ActualSalesVATAmount":66
}
PUT Operation
Updates project details for the specified project number using the following URL –URL : /projects/{number}
{number} in the URL should be replaced with the number of the project to be updated.
To update project details you need to provide the whole project object (similar to the GET project response) and you need to update the fields you wish to. Project number is a mandatory field for this operation. It cannot be less than or equal to zero.
Example request for PUT of project
{
"Project":{
"ActualJournalsAmount":0,
"ActualPurchasesAmount":0,
"ActualSalesAmount":439,
"CustomerId":6657,
"CustomerName":"Brian Hayes",
"Description":"Updated",
"StartDate":"2012-10-09 12:00:00 +05:30",
"EndDate":"2012-10-10 12:00:00 +05:30",
"AssociatedQuotesCount":6,
"ExcludeVAT":0,
"Name":"Project10",
"Note":"",
"Number":10,
"Reference":"test",
"Status":1,
"StatusName":"Active",
"TargetPurchasesAmount":0,
"TargetSalesAmount":100,
"ActualPurchasesVATAmount":0,
"ActualSalesVATAmount":69
}
}
DELETE Operation
Deletes the project with the project number specified in the URL –URL : /projects/{number}?reassignnumber={reassignnumber}
{number} in the URL should be replaced with the number of the project to be deleted. It cannot be less than or equal to zero.
{reassignnumber} is an optional parameter which can be used to specify an alternate project number for the entities which are associated with the project that is being deleted.