Project tracking and time management API for Xero. Supports creating and managing projects, tasks, time entries, and expenses. Enables integration of project-based billing with Xero accounting for professional services and project-based businesses.
openapi: 3.0.0
info:
version: 11.1.0
title: Xero Projects API
description: This is the Xero Projects API
termsOfService: https://developer.xero.com/xero-developer-platform-terms-conditions/
contact:
name: Xero Platform Team
email: [email protected]
url: https://developer.xero.com
license:
name: MIT
url: https://github.com/XeroAPI/Xero-OpenAPI/blob/master/LICENSE
servers:
- description: Xero API server for projects
url: https://api.xero.com/projects.xro/2.0
paths:
/Projects:
parameters:
- $ref: "#/components/parameters/requiredHeader"
get:
security:
- OAuth2:
- projects
- projects.read
tags:
- Project
summary: Xero Retrieves all projects
operationId: getProjects
description: Allows you to retrieve, create and update projects.
parameters:
- name: projectIds
x-snake: project_ids
in: query
required: false
description: Search for all projects that match a comma separated list of projectIds
schema:
type: array
items:
type: string
format: uuid
- name: contactID
x-snake: contact_id
in: query
required: false
description: Filter for projects for a specific contact
schema:
type: string
format: uuid
- name: states
in: query
required: false
description: Filter for projects in a particular state (INPROGRESS or CLOSED)
schema:
type: string
- name: page
in: query
required: false
description: set to 1 by default. The requested number of the page in paged response - Must be a number greater than 0.
schema:
type: integer
example: 1
default: 1
- name: pageSize
x-snake: page_size
in: query
required: false
description: 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.
schema:
type: integer
minimum: 1
maximum: 500
default: 50
example: 100
responses:
"200":
description: OK/success, returns a list of project objects
content:
application/json:
schema:
$ref: "#/components/schemas/Projects"
example:
pagination:
page: 1
pageSize: 50
pageCount: 1
itemCount: 9
items:
- projectId: b021e7cb-1903-4292-b48b-5b27b4271e3e
contactId: 216830cb-9a68-487e-928b-c1a7ccc4fc81
name: FooProject28916
currencyCode: AUD
minutesLogged: 180
totalTaskAmount:
currency: AUD
value: 60.0
totalExpenseAmount:
currency: AUD
value: 499.0
minutesToBeInvoiced: 180
taskAmountToBeInvoiced:
currency: AUD
value: 60.0
taskAmountInvoiced:
currency: AUD
value: 0.0
expenseAmountToBeInvoiced:
currency: AUD
value: 499.0
expenseAmountInvoiced:
currency: AUD
value: 0.0
projectAmountInvoiced:
currency: AUD
value: 0.0
deposit:
currency: AUD
value: 0.0
depositApplied:
currency: AUD
value: 0.0
creditNoteAmount:
currency: AUD
value: 0.0
totalInvoiced:
currency: AUD
value: 0.0
totalToBeInvoiced:
currency: AUD
value: 559.0
deadlineUtc: "2020-03-03T15:00:00Z"
estimate:
currency: AUD
value: 99.99
status: INPROGRESS
"400":
$ref: "#/components/responses/400Error"
post:
security:
- OAuth2:
- projects
tags:
- Project
summary: Xero Create one or more new projects
parameters:
- $ref: "#/components/parameters/idempotencyKey"
operationId: createProject
requestBody:
required: true
description: Create a new project with ProjectCreateOrUpdate object
content:
application/json:
schema:
$ref: "#/components/schemas/ProjectCreateOrUpdate"
example: '{ "contactId": "00000000-0000-0000-000-000000000000", "name": "New Kitchen", "deadlineUtc": "2019-12-10T12:59:59Z", "estimateAmount": "99.99" }'
responses:
"201":
description: OK/success, returns the new project object
content:
application/json:
schema:
$ref: "#/components/schemas/Project"
example:
projectId: ed957eee-bc6f-4f52-a663-aa42e6af9620
contactId: 216830cb-9a68-487e-928b-c1a7ccc4fc81
name: New Kitchen
currencyCode: AUD
minutesLogged: 0
totalTaskAmount:
currency: AUD
value: 0.0
totalExpenseAmount:
currency: AUD
value: 0.0
minutesToBeInvoiced: 0
taskAmountToBeInvoiced:
currency: AUD
value: 0.0
taskAmountInvoiced:
currency: AUD
value: 0.0
expenseAmountToBeInvoiced:
currency: AUD
value: 0.0
expenseAmountInvoiced:
currency: AUD
value: 0.0
projectAmountInvoiced:
currency: AUD
value: 0.0
deposit:
currency: AUD
value: 0.0
depositApplied:
currency: AUD
value: 0.0
creditNoteAmount:
currency: AUD
value: 0.0
totalInvoiced:
currency: AUD
value: 0.0
totalToBeInvoiced:
currency: AUD
value: 0.0
deadlineUtc: "2020-03-03T15:00:00Z"
estimate:
currency: AUD
value: 99.99
status: INPROGRESS
"400":
$ref: "#/components/responses/400Error"
/Projects/{projectId}:
parameters:
- $ref: "#/components/parameters/requiredHeader"
get:
security:
- OAuth2:
- projects
- projects.read
tags:
- Project
summary: Xero Retrieves a single project
operationId: getProject
description: Allows you to retrieve a specific project using the projectId
parameters:
- name: projectId
x-snake: project_id
in: path
required: true
description: You can specify an individual project by appending the projectId to the endpoint
schema:
type: string
format: uuid
responses:
"200":
description: OK/success, returns the specified project object
content:
application/json:
schema:
$ref: "#/components/schemas/Project"
example:
projectId: b021e7cb-1903-4292-b48b-5b27b4271e3e
contactId: 216830cb-9a68-487e-928b-c1a7ccc4fc81
name: Remodeling 2012
currencyCode: AUD
minutesLogged: 180
totalTaskAmount:
currency: AUD
value: 60.0
totalExpenseAmount:
currency: AUD
value: 499.0
minutesToBeInvoiced: 180
taskAmountToBeInvoiced:
currency: AUD
value: 60.0
taskAmountInvoiced:
currency: AUD
value: 0.0
expenseAmountToBeInvoiced:
currency: AUD
value: 499.0
expenseAmountInvoiced:
currency: AUD
value: 0.0
projectAmountInvoiced:
currency: AUD
value: 0.0
deposit:
currency: AUD
value: 0.0
depositApplied:
currency: AUD
value: 0.0
creditNoteAmount:
currency: AUD
value: 0.0
totalInvoiced:
currency: AUD
value: 0.0
totalToBeInvoiced:
currency: AUD
value: 559.0
deadlineUtc: "2020-03-03T15:00:00Z"
estimate:
currency: AUD
value: 99.99
status: INPROGRESS
"400":
$ref: "#/components/responses/400Error"
put:
security:
- OAuth2:
- projects
tags:
- Project
summary: Xero Updates a specific project
operationId: updateProject
description: Allows you to update a specific projects.
parameters:
- $ref: "#/components/parameters/idempotencyKey"
- name: projectId
x-snake: project_id
in: path
required: true
description: You can specify an individual project by appending the projectId to the endpoint
schema:
type: string
format: uuid
requestBody:
required: true
description: Request of type ProjectCreateOrUpdate
content:
application/json:
schema:
$ref: "#/components/schemas/ProjectCreateOrUpdate"
example: '{ "name": "New Kitchen", "deadlineUtc": "2017-04-23T18:25:43.511Z", "estimateAmount": 99.99 }'
responses:
"204":
description: Success - return response 204 no content
x-isEmpty: true
"400":
$ref: "#/components/responses/400Error"
patch:
security:
- OAuth2:
- projects
tags:
- Project
summary: Xero creates a project for the specified contact
operationId: patchProject
description: Allows you to update a specific projects.
parameters:
- $ref: "#/components/parameters/idempotencyKey"
- name: projectId
x-snake: project_id
in: path
required: true
description: You can specify an individual project by appending the projectId to the endpoint
schema:
type: string
format: uuid
requestBody:
required: true
description: Update the status of an existing Project
content:
application/json:
schema:
$ref: "#/components/schemas/ProjectPatch"
example: '{ "status": "INPROGRESS" }'
responses:
"204":
description: Success - return response 204 no content
x-isEmpty: true
"400":
$ref: "#/components/responses/400Error"
/ProjectsUsers:
parameters:
- $ref: "#/components/parameters/requiredHeader"
get:
security:
- OAuth2:
- projects
- projects.read
tags:
- Project
summary: Xero Retrieves a list of all project users
operationId: getProjectUsers
description: Allows you to retrieve the users on a projects.
parameters:
- name: page
in: query
required: false
description: set to 1 by default. The requested number of the page in paged response - Must be a number greater than 0.
schema:
type: integer
example: 1
default: 1
- name: pageSize
x-snake: page_size
in: query
required: false
description: 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.
schema:
type: integer
minimum: 1
maximum: 500
default: 50
example: 100
responses:
"200":
description: OK/success, returns a list of project users
content:
application/json:
schema:
$ref: "#/components/schemas/ProjectUsers"
example:
pagination:
page: 1
pageSize: 50
pageCount: 1
itemCount: 2
items:
- userId: 740add2a-a703-4b8a-a670-1093919c2040
name: Test User
email: [email protected]
- userId: 00000000-0000-0000-0000-000000000000
name: API Team
email: [email protected]
"400":
$ref: "#/components/responses/400Error"
/Projects/{projectId}/Tasks:
parameters:
- $ref: "#/components/parameters/requiredHeader"
get:
security:
- OAuth2:
- projects
- projects.read
tags:
- Project
summary: Xero Retrieves all project tasks
operationId: getTasks
description: Allows you to retrieve a specific project
parameters:
- name: projectId
x-snake: project_id
in: path
required: true
description: You can specify an individual project by appending the projectId to the endpoint
schema:
type: string
format: uuid
- name: page
in: query
description: Set to 1 by default. The requested number of the page in paged response - Must be a number greater than 0.
schema:
type: integer
example: 1
- name: pageSize
x-snake: page_size
in: query
description: 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.
schema:
type: integer
example: 10
- name: taskIds
x-snake: task_ids
in: query
description: Search for all tasks that match a comma separated list of taskIds, i.e. GET https://.../tasks?taskIds={taskID},{taskID}
schema:
type: string
- name: chargeType
$ref: "#/components/parameters/chargeType"
responses:
"200":
description: OK/success, returns a list of task objects
content:
application/json:
schema:
$ref: "#/components/schemas/Tasks"
example:
pagination:
page: 1
pageSize: 50
pageCount: 1
itemCount: 1
items:
- name: Demolition
rate:
currency: AUD
value: 20.0
chargeType: TIME
status: ACTIVE
estimateMinutes: 12000
taskId: 7be77337-feec-4458-bb1b-dbaa5a4aafce
projectId: b021e7cb-1903-4292-b48b-5b27b4271e3e
totalMinutes: 180
totalAmount:
currency: AUD
value: 60.0
minutesToBeInvoiced: 180
minutesInvoiced: 0
nonChargeableMinutes: 0
fixedMinutes: 0
amountToBeInvoiced:
currency: AUD
value: 60.0
amountInvoiced:
currency: AUD
value: 0.0
"400":
$ref: "#/components/responses/400Error"
post:
security:
- OAuth2:
- projects
tags:
- Project
summary: Xero Allows you to create a task
operationId: createTask
description: Allows you to create a specific task
parameters:
- $ref: "#/components/parameters/idempotencyKey"
- name: projectId
x-snake: project_id
in: path
required: true
description: You can create a task on a specified projectId
schema:
type: string
format: uuid
requestBody:
required: true
description: The task object you are creating
content:
application/json:
schema:
$ref: "#/components/schemas/TaskCreateOrUpdate"
example: '{ "status": "INPROGRESS" }'
responses:
"201":
description: OK/success, returns the new task object
content:
application/json:
schema:
$ref: "#/components/schemas/Task"
example:
name: Demolition
rate:
currency: AUD
value: 20
chargeType: TIME
status: ACTIVE
estimateMinutes: 12000
taskId: 00000000-0000-0000-0000-000000000000
projectId: 00000000-0000-0000-0000-000000000000
totalMinutes: 300
totalAmount:
currency: AUD
value: 100
minutesToBeInvoiced: 300
minutesInvoiced: 0
nonChargeableMinutes: 0
fixedMinutes: 0
amountToBeInvoiced:
currency: AUD
value: 100
amountInvoiced:
currency: AUD
value: 0
"400":
$ref: "#/components/responses/400Error"
/Projects/{projectId}/Tasks/{taskId}:
parameters:
- $ref: "#/components/parameters/requiredHeader"
get:
security:
- OAuth2:
- projects
- projects.read
tags:
- Project
summary: Xero Retrieves a single project task
operationId: getTask
description: Allows you to retrieve a specific project
parameters:
- name: projectId
x-snake: project_id
in: path
required: true
description: You can specify an individual project by appending the projectId to the endpoint
schema:
type: string
format: uuid
- name: taskId
x-snake: task_id
in: path
required: true
description: You can specify an individual task by appending the taskId to the endpoint, i.e. GET https://.../tasks/{taskID}
schema:
type: string
format: uuid
responses:
"200":
description: OK/success, returns the specified task object
content:
application/json:
schema:
$ref: "#/components/schemas/Task"
example:
name: Demolition
rate:
currency: AUD
value: 20
chargeType: TIME
status: ACTIVE
estimateMinutes: 12000
taskId: 7be77337-feec-4458-bb1b-dbaa5a4aafce
projectId: b021e7cb-1903-4292-b48b-5b27b4271e3e
totalMinutes: 300
totalAmount:
currency: AUD
value: 100
minutesToBeInvoiced: 300
minutesInvoiced: 0
nonChargeableMinutes: 0
fixedMinutes: 0
amountToBeInvoiced:
currency: AUD
value: 100
amountInvoiced:
currency: AUD
value: 0
"400":
$ref: "#/components/responses/400Error"
put:
security:
- OAuth2:
- projects
tags:
- Project
summary: Xero Allows you to update a task
operationId: updateTask
description: Allows you to update a specific task
parameters:
- $ref: "#/components/parameters/idempotencyKey"
- name: projectId
x-snake: project_id
in: path
required: true
description: You can specify an individual project by appending the projectId to the endpoint
schema:
type: string
format: uuid
- name: taskId
x-snake: task_id
in: path
required: true
description: You can specify an individual task by appending the id to the endpoint
schema:
type: string
format: uuid
requestBody:
required: true
description: The task object you are updating
content:
application/json:
schema:
$ref: "#/components/schemas/TaskCreateOrUpdate"
example: ""
responses:
"204":
description: OK/Success - return response 204 no content
x-isEmpty: true
"400":
$ref: "#/components/responses/400Error"
delete:
security:
- OAuth2:
- projects
tags:
- Project
summary: Xero Allows you to delete a task
operationId: deleteTask
description: Allows you to delete a specific task
parameters:
- name: projectId
x-snake: project_id
in: path
required: true
description: You can specify an individual project by appending the projectId to the endpoint
schema:
type: string
format: uuid
- name: taskId
x-snake: task_id
in: path
required: true
description: You can specify an individual task by appending the id to the endpoint
schema:
type: string
format: uuid
responses:
"204":
description: Success - return response 204 no content
x-isEmpty: true
"400":
$ref: "#/components/responses/400Error"
/Projects/{projectId}/Time:
parameters:
- $ref: "#/components/parameters/requiredHeader"
get:
security:
- OAuth2:
- projects
- projects.read
tags:
- Project
summary: Xero Retrieves all time entries associated with a specific project
operationId: getTimeEntries
description: Allows you to retrieve the time entries associated with a specific project
parameters:
- name: projectId
x-snake: project_id
in: path
required: true
description: Identifier of the project, that the task (which the time entry is logged against) belongs to.
schema:
type: string
format: uuid
- name: userId
x-snake: user_id
in: query
description: The xero user identifier of the person who logged time.
schema:
type: string
format: uuid
- name: taskId
x-snake: task_id
in: query
description: Identifier of the task that time entry is logged against.
schema:
type: string
format: uuid
- name: invoiceId
x-snake: invoice_id
in: query
description: Finds all time entries for this invoice.
schema:
type: string
format: uuid
- name: contactId
x-snake: contact_id
in: query
description: Finds all time entries for this contact identifier.
schema:
type: string
format: uuid
- name: page
in: query
description: Set to 1 by default. The requested number of the page in paged response - Must be a number greater than 0.
schema:
type: integer
example: 1
- name: pageSize
x-snake: page_size
in: query
description: 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.
schema:
type: integer
example: 10
- name: states
in: query
description: Comma-separated list of states to find. Will find all time entries that are in the status of whatever is specified.
schema:
type: array
items:
type: string
- name: isChargeable
x-snake: is_chargeable
in: query
description: Finds all time entries which relate to tasks with the charge type `TIME` or `FIXED`.
schema:
type: boolean
- name: dateAfterUtc
x-snake: date_after_utc
in: query
description: ISO 8601 UTC date. Finds all time entries on or after this date filtered on the `dateUtc` field.
schema:
type: string
format: date-time
- name: dateBeforeUtc
x-snake: date_before_utc
in: query
description: ISO 8601 UTC date. Finds all time entries on or before this date filtered on the `dateUtc` field.
schema:
type: string
format: date-time
responses:
"200":
description: OK/success, returns a list of time entry objects
content:
application/json:
schema:
$ref: "#/components/schemas/TimeEntries"
example:
pagination:
page: 1
pageSize: 50
pageCount: 1
itemCount: 9
items:
- timeEntryId: 3cd35eca-704f-4bca-b258-236028ae8ed1
userId: 740add2a-a703-4b8a-a670-1093919c2040
projectId: b021e7cb-1903-4292-b48b-5b27b4271e3e
taskId: 7be77337-feec-4458-bb1b-dbaa5a4aafce
dateUtc: "2020-02-27T15:00:00Z"
dateEnteredUtc: "2020-02-28T03:24:29.2215641Z"
duration: 45
description: My description
status: ACTIVE
- timeEntryId: 00000000-0000-0000-0000-000000000000
userId: 00000000-0000-0000-0000-000000000000
projectId: 00000000-0000-0000-0000-000000000000
taskId: 00000000-0000-0000-0000-000000000000
dateUtc: "2020-02-26T15:00:00Z"
dateEnteredUtc: "2020-02-28T03:24:29.2215641Z"
duration: 30
description: My description
status: ACTIVE
"400":
$ref: "#/components/responses/400Error"
post:
security:
- OAuth2:
- projects
tags:
- Project
summary: Xero Creates a time entry for a specific project
operationId: createTimeEntry
description: Allows you to create a specific task
parameters:
- $ref: "#/components/parameters/idempotencyKey"
- name: projectId
x-snake: project_id
in: path
required: true
description: You can specify an individual project by appending the projectId to the endpoint
schema:
type: string
format: uuid
requestBody:
required: true
description: The time entry object you are creating
content:
application/json:
schema:
$ref: "#/components/schemas/TimeEntryCreateOrUpdate"
example:
userId: 00000000-0000-0000-0000-000000000000
taskId: 00000000-0000-0000-0000-000000000000
dateUtc: "2020-02-26T15:00:00Z"
duration: 30
description: My description
responses:
"200":
description: OK/success, returns the newly created time entry
content:
application/json:
schema:
$ref: "#/components/schemas/TimeEntry"
example:
timeEntryId: c6539534-f1d2-43a6-80df-3bd1f8aca24d
userId: c6539534-f1d2-43a6-80df-3bd1f8aca24d
projectId: b021e7cb-1903-4292-b48b-5b27b4271e3e
taskId: 7be77337-feec-4458-bb1b-dbaa5a4aafce
dateUtc: "2020-02-26T15:00:00Z"
dateEnteredUtc: "2020-02-28T20:37:42.8652832Z"
duration: 30
description: My description
status: ACTIVE
"400":
$ref: "#/components/responses/400Error"
/Projects/{projectId}/Time/{timeEntryId}:
parameters:
- $ref: "#/components/parameters/requiredHeader"
get:
security:
- OAuth2:
- projects
- projects.read
tags:
- Project
summary: Xero Retrieves a single time entry for a specific project
operationId: getTimeEntry
description: Allows you to get a single time entry in a project
parameters:
- name: projectId
x-snake: project_id
in: path
required: true
description: You can specify an individual project by appending the projectId to the endpoint
schema:
type: string
format: uuid
- name: timeEntryId
x-snake: time_entry_id
in: path
required: true
description: You can specify an individual time entry by appending the id to the endpoint
schema:
type: string
format: uuid
responses:
"200":
description: OK/success, returns the specified time entry
content:
application/json:
schema:
$ref: "#/components/schemas/TimeEntry"
example:
timeEntryId: 3cd35eca-704f-4bca-b258-236028ae8ed1
userId: 740add2a-a703-4b8a-a670-1093919c2040
projectId: b021e7cb-1903-4292-b48b-5b27b4271e3e
taskId: 7be77337-feec-4458-bb1b-dbaa5a4aafce
dateUtc: "2020-02-27T15:00:00Z"
dateEnteredUtc: "2020-02-21T21:41:22.2642727Z"
duration: 45
description: My description
status: ACTIVE
"400":
$ref: "#/components/responses/400Error"
put:
security:
- OAuth2:
- projects
tags:
- Project
summary: Xero Updates a time entry for a specific project
operationId: updateTimeEntry
description: Allows you to update time entry in a project
parameters:
- $ref: "#/components/parameters/idempotencyKey"
- name: projectId
x-snake: project_id
in: path
required: true
description: You can specify an individual project by appending the projectId to the endpoint
schema:
type: string
format: uuid
- name: timeEntryId
x-snake: time_entry_id
in: path
required: true
description: You can specify an individual time entry by appending the id to the endpoint
schema:
type: string
format: uuid
requestBody:
required: true
description: The time entry object you are updating
content:
application/json:
schema:
$ref: "#/components/schemas/TimeEntryCreateOrUpdate"
example:
userId: 00000000-0000-0000-0000-000000000000
taskId: 00000000-0000-0000-0000-000000000000
dateUtc: "2020-02-27T15:00:00Z"
duration: 45
description: My UPDATED description
responses:
"204":
description: Success - return response 204 no content
x-isEmpty: true
# --- truncated at 32 KB (49 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/xero/refs/heads/main/openapi/xero-projects-openapi.yml