Projects

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

NameTypeDescription
Number*NumericUnique number given to the project
ActualJournalsAmountNumericBalance of journals (Credit – Debit) associated with the project
ActualPurchasesAmountNumericTotal value of purchases against the project
ActualSalesAmountNumericSum of the amounts of all invoices associated with the project
CustomerIdNumericId of the customer against whom the project has been created
CustomerNameStringName of the customer against whom the project has been created
DescriptionStringDescription of the project
StartDateDateStart date of the project For example: JSON : [JSONDATE], XML : [XMLDATE]
AssociatedQuotesCountNumericCount of quotes created against the given project
ExcludeVATNumericSetting for whether VAT is to be excluded or not for the project
NameStringName of the project
NoteStringNotes belonging to the project
ReferenceStringReference text for the project
EndDateDateEnd date of the project. For example: JSON : [JSONDATE] XML : [XMLDATE]
StatusNumericValue which states whether the project is complete, active or archived. Value 0 = complete, 1 = active, 2 = archived
StatusNameStringName of the project state (complete, active or archived)
TargetPurchasesAmountNumericValue of purchases against the project
VatAmountBankTransactionsNumericTotal VAT amount on bank transactions for the project
ActualSalesVATAmountNumericTotal VAT amount on sales against the project
TargetSalesAmountNumericValue of sales against the project
ActualPurchasesVATAmountNumericTotal VAT amount on purchases against the project
WorkInProgressAmountNumericThe 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

NameDescription
customerCodeRetrieve 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.

See how KashFlow works with your business and your books