The following elements are returned in the projects response
projectId | Identifier of the project. |
contactId | Identifier of the contact this project was created for. See Contacts. |
name | Name of the project. |
currencyCode | A project's currency code in ISO-4217 format. Will be set to the organisation's default currency, until a time where Projects supports multi-currency projects. |
minutesLogged | A total of minutes logged against all tasks on the Project. |
totalTaskAmount | A summation of the total actuals amount of each project task. An object containing currency and value. |
totalExpenseAmount | A summation of the total actuals amount of each project expense. An object containing currency and value. |
minutesToBeInvoiced | Minutes which have not been invoiced across all chargeable tasks in the project. |
taskAmountToBeInvoiced | A summation of `amountToBeInvoiced` of each task in the project. An object containing currency and value. |
taskAmountInvoiced | A summation of `amountInvoiced` of each task in the project. An object containing currency and value. |
expenseAmountToBeInvoiced | A summation of 'total' of each expense which is not invoiced in the project. An object containing currency and value. |
expenseAmountInvoiced | A summation of 'total' of each expense which is invoiced in the project. An object containing currency and value. |
projectAmountInvoiced | A summation of project amount invoices that is invoiced in the project. An object containing currency and value. |
deposit | Deposit for the project. An object containing currency and value. |
depositApplied | Deposit amounts which have been applied to invoice/s as credit. An object containing currency and value. |
creditNoteAmount | A summation of credit notes in the project. An object containing currency and value. |
deadlineUTC | Deadline for the project. UTC Date Time in ISO-8601 format. |
totalInvoiced | A summation of the values `taskAmountInvoiced`, `expenseAmountInvoiced`, `projectAmountInvoiced`, `deposit`, `depositApplied` and `creditNoteAmount`. An object containing currency and value. |
totalToBeInvoiced | A summation of the values values `taskAmountToBeInvoiced` and `expenseAmountToBeInvoiced`. An object containing currency and value. |
estimate | Estimate for the project (currency and value). An object containing currency and value. |
status | Status of the project. INPROGRESS or CLOSED. A project is created with status of `INPROGRESS`. To change the status of a project see [PATCH]. |
projectId | You can specify an individual project by appending the projectId to the endpoint, i.e. GET https://.../projects/{projectId} |
projectIds | Search for all projects that match a comma separated list of projectIds, i.e. GET https://.../projects?projectIDs={projectId},{projectId} |
contactID | Filter for projects for a specific contact |
states | Filter for projects in a particular state (INPROGRESS or CLOSED) |
page | set to 1 by default. The requested number of the page in paged response - Must be a number greater than 0. |
pageSize | Optional, it is set to 50 by default. The number of items to return per page in a paged response - Must be a number between 1 and 500. |
Example response when searching projects
GET https://api.xero.com/projects.xro/2.0/projects?contactId=01234567-89ab-cdef-0123-456789abcdef&states=INPROGRESS&page=1&pageSize=50
{ "pagination": { "page": 1, "pageSize": 50, "pageCount": 1, "itemCount": 1 } }, "items": [ { "projectId": "254553fa-2be8-4991-bd5e-70a97ea12ef8", "contactId": "01234567-89ab-cdef-0123-456789abcdef", "name": "New Kitchen", "currencyCode": "", "minutesLogged": 0, "totalTaskAmount": { "currency": "NZD", "value": 0 }, "totalExpenseAmount": { "currency": "NZD", "value": 0 }, "minutesToBeInvoiced": 0, "taskAmountToBeInvoiced": { "currency": "NZD", "value": 0 }, "taskAmountInvoiced": { "currency": "NZD", "value": 0 }, "expenseAmountToBeInvoiced": { "currency": "NZD", "value": 0 }, "expenseAmountInvoiced": { "currency": "NZD", "value": 0 }, "projectAmountInvoiced": { "currency": "NZD", "value": 0 }, "deposit": { "currency": "NZD", "value": 0 }, "depositApplied": { "currency": "NZD", "value": 0 }, "creditNoteAmount": { "currency": "NZD", "value": 0 }, "deadlineUtc": "", "totalInvoiced": { "currency": "NZD", "value": 0 }, "totalToBeInvoiced": { "currency": "NZD", "value": 0 }, "estimate": { "currency": "NZD", "value": 99.99 }, "status": "INPROGRESS" } ] }
The following are required when creating a Project | |
contactId | Identifier of the contact this project was created for. See Contacts. Currently only available when creating a project. |
Name | Name of the project. |
The following are optional when creating a Project | |
deadlineUTC | Deadline for the project. UTC Date Time in ISO-8601 format. |
estimateAmount | Estimate for the project. |
Example request creating a project
POST https://api.xero.com/projects.xro/2.0/Projects
{ "contactId": "01234567-89ab-cdef-0123-456789abcdef", "name": "New Kitchen", "deadlineUtc": "2017-04-23T18:25:43.511Z", "estimateAmount": 99.99 }
The following are required when updating a Project | |
Name | Name of the project. |
The following are optional when updating a Project | |
deadlineUTC | Deadline for the project. UTC Date Time in ISO-8601 format. |
estimateAmount | Estimate for the project. |
Example request to update a project's details
PUT https://api.xero.com/projects.xro/2.0/Projects/254553fa-2be8-4991-bd5e-70a97ea12ef8
{ "name": "New Kitchen", "deadlineUtc": "2017-04-23T18:25:43.511Z", "estimateAmount": 99.99 }
The following are required when updating a Project's status | |
Status | INPROGRESS or CLOSED |
Example request to update a project's status
PATCH https://api.xero.com/projects.xro/2.0/Projects/254553fa-2be8-4991-bd5e-70a97ea12ef8
{ "status": "INPROGRESS" }