xero.projects
Module xero.projects
API
Definitions
ballerinax/xero.projects Ballerina library
Overview
Xero is a cloud-based accounting platform for small and medium-sized businesses. Its Projects API lets you track time and costs against client work, and covers projects, the tasks within them, time entries, and the users who can be assigned work.
The Xero Projects connector provides a Ballerina client for version 2.0 of the Xero Projects API. It lets you create and update projects, manage tasks and their charge rates, log and edit time entries, and list the users available for project work from your integrations.
Key features
- Create, retrieve, update and close projects for your contacts
- Manage project tasks with time-based, fixed or non-chargeable rates
- Log, update and delete time entries and filter them by user, task, date or invoice
- List project users and page through large result sets
Setup guide
To use the Xero Projects connector, you need a Xero app that can call the Projects API for your organisation.
-
Sign in to the Xero developer portal and select New app.
-
Enter an app name and company or application URL, choose the Web app integration type, and add a redirect URI for your application.
-
Open the Configuration page of the app and copy the Client id. Generate a Client secret and copy it.
-
Run the OAuth 2.0 authorization code flow against
https://login.xero.com/identity/connect/authorizerequesting theprojects,projects.readandoffline_accessscopes. Exchange the returned code athttps://identity.xero.com/connect/tokenfor an access token and a refresh token. -
Call
GET https://api.xero.com/connectionswith the access token and copy thetenantIdof the organisation you want to work with. Every operation of the connector takes it as thexeroTenantIdheader.
Quickstart
To use the xero.projects connector in your Ballerina application, update the .bal file as follows:
Step 1: Import the connector.
import ballerinax/xero.projects;
Step 2: Create a Config.toml file with your credentials.
clientId = "<client-id>" clientSecret = "<client-secret>" refreshToken = "<refresh-token>" tenantId = "<xero-tenant-id>"
Step 3: Create a client and read the configuration.
configurable string clientId = ?; configurable string clientSecret = ?; configurable string refreshToken = ?; configurable string tenantId = ?; projects:Client projectsClient = check new ({ auth: { clientId, clientSecret, refreshToken } });
Step 4: List the projects of your organisation.
public function main() returns error? { projects:ProjectList _ = check projectsClient->listProjects({xeroTenantId: tenantId}); }
Examples
The Xero Projects connector provides practical examples illustrating usage in various scenarios. Explore these examples, covering the following use cases:
-
Project time logging - Create a project for a contact, add a chargeable task, log time against it and read the entries back.
-
Project progress report - Compare the estimated and logged minutes of every in-progress project.
Clients
xero.projects: Client
This is the Xero Projects API
Constructor
Gets invoked to initialize the connector.
init (ConnectionConfig config, string serviceUrl)- config ConnectionConfig - The configurations to be used when initializing the
connector
- serviceUrl string "https://api.xero.com/projects.xro/2.0" - URL of the target service
listProjects
function listProjects(ListProjectsHeaders headers, *ListProjectsQueries queries) returns ProjectList|errorRetrieves all projects
Parameters
- headers ListProjectsHeaders - Headers to be sent with the request
- queries *ListProjectsQueries - Queries to be sent with the request
Return Type
- ProjectList|error - OK/success, returns a list of project objects
createProject
function createProject(CreateProjectHeaders headers, ProjectCreateOrUpdate payload) returns Project|errorCreate one or more new projects
Parameters
- headers CreateProjectHeaders - Headers to be sent with the request
- payload ProjectCreateOrUpdate - Create a new project with ProjectCreateOrUpdate object
getProject
function getProject(string projectId, GetProjectHeaders headers) returns Project|errorRetrieves a single project
Parameters
- projectId string - You can specify an individual project by appending the projectId to the endpoint
- headers GetProjectHeaders - Headers to be sent with the request
updateProject
function updateProject(string projectId, UpdateProjectHeaders headers, ProjectCreateOrUpdate payload) returns error?Updates a specific project
Parameters
- projectId string - You can specify an individual project by appending the projectId to the endpoint
- headers UpdateProjectHeaders - Headers to be sent with the request
- payload ProjectCreateOrUpdate - Request of type ProjectCreateOrUpdate
Return Type
- error? - Success - return response 204 no content
updateProjectStatus
function updateProjectStatus(string projectId, UpdateProjectStatusHeaders headers, ProjectPatch payload) returns error?Updates the status of a specific project
Parameters
- projectId string - You can specify an individual project by appending the projectId to the endpoint
- headers UpdateProjectStatusHeaders - Headers to be sent with the request
- payload ProjectPatch - Update the status of an existing Project
Return Type
- error? - Success - return response 204 no content
listProjectUsers
function listProjectUsers(ListProjectUsersHeaders headers, *ListProjectUsersQueries queries) returns ProjectUserList|errorRetrieves a list of all project users
Parameters
- headers ListProjectUsersHeaders - Headers to be sent with the request
- queries *ListProjectUsersQueries - Queries to be sent with the request
Return Type
- ProjectUserList|error - OK/success, returns a list of project users
listTasks
function listTasks(string projectId, ListTasksHeaders headers, *ListTasksQueries queries) returns TaskList|errorRetrieves all project tasks
Parameters
- projectId string - You can specify an individual project by appending the projectId to the endpoint
- headers ListTasksHeaders - Headers to be sent with the request
- queries *ListTasksQueries - Queries to be sent with the request
createTask
function createTask(string projectId, CreateTaskHeaders headers, TaskCreateOrUpdate payload) returns Task|errorAllows you to create a task
Parameters
- projectId string - You can create a task on a specified projectId
- headers CreateTaskHeaders - Headers to be sent with the request
- payload TaskCreateOrUpdate - The task object you are creating
getTask
function getTask(string projectId, string taskId, GetTaskHeaders headers) returns Task|errorRetrieves a single project task
Parameters
- projectId string - You can specify an individual project by appending the projectId to the endpoint
- taskId string - You can specify an individual task by appending the taskId to the endpoint, i.e. GET https://.../tasks/{taskID}
- headers GetTaskHeaders - Headers to be sent with the request
updateTask
function updateTask(string projectId, string taskId, UpdateTaskHeaders headers, TaskCreateOrUpdate payload) returns error?Allows you to update a task
Parameters
- projectId string - You can specify an individual project by appending the projectId to the endpoint
- taskId string - You can specify an individual task by appending the id to the endpoint
- headers UpdateTaskHeaders - Headers to be sent with the request
- payload TaskCreateOrUpdate - The task object you are updating
Return Type
- error? - OK/Success - return response 204 no content
deleteTask
function deleteTask(string projectId, string taskId, DeleteTaskHeaders headers) returns error?Allows you to delete a task
Parameters
- projectId string - You can specify an individual project by appending the projectId to the endpoint
- taskId string - You can specify an individual task by appending the id to the endpoint
- headers DeleteTaskHeaders - Headers to be sent with the request
Return Type
- error? - Success - return response 204 no content
listTimeEntries
function listTimeEntries(string projectId, ListTimeEntriesHeaders headers, *ListTimeEntriesQueries queries) returns TimeEntryList|errorRetrieves all time entries associated with a specific project
Parameters
- projectId string - Identifier of the project, that the task (which the time entry is logged against) belongs to
- headers ListTimeEntriesHeaders - Headers to be sent with the request
- queries *ListTimeEntriesQueries - Queries to be sent with the request
Return Type
- TimeEntryList|error - OK/success, returns a list of time entry objects
createTimeEntry
function createTimeEntry(string projectId, CreateTimeEntryHeaders headers, TimeEntryCreateOrUpdate payload) returns TimeEntry|errorCreates a time entry for a specific project
Parameters
- projectId string - You can specify an individual project by appending the projectId to the endpoint
- headers CreateTimeEntryHeaders - Headers to be sent with the request
- payload TimeEntryCreateOrUpdate - The time entry object you are creating
getTimeEntry
function getTimeEntry(string projectId, string timeEntryId, GetTimeEntryHeaders headers) returns TimeEntry|errorRetrieves a single time entry for a specific project
Parameters
- projectId string - You can specify an individual project by appending the projectId to the endpoint
- timeEntryId string - You can specify an individual time entry by appending the id to the endpoint
- headers GetTimeEntryHeaders - Headers to be sent with the request
updateTimeEntry
function updateTimeEntry(string projectId, string timeEntryId, UpdateTimeEntryHeaders headers, TimeEntryCreateOrUpdate payload) returns error?Updates a time entry for a specific project
Parameters
- projectId string - You can specify an individual project by appending the projectId to the endpoint
- timeEntryId string - You can specify an individual time entry by appending the id to the endpoint
- headers UpdateTimeEntryHeaders - Headers to be sent with the request
- payload TimeEntryCreateOrUpdate - The time entry object you are updating
Return Type
- error? - Success - return response 204 no content
deleteTimeEntry
function deleteTimeEntry(string projectId, string timeEntryId, DeleteTimeEntryHeaders headers) returns error?Deletes a time entry for a specific project
Parameters
- projectId string - You can specify an individual project by appending the projectId to the endpoint
- timeEntryId string - You can specify an individual task by appending the id to the endpoint
- headers DeleteTimeEntryHeaders - Headers to be sent with the request
Return Type
- error? - Success - return response 204 no content
Records
xero.projects: Amount
Monetary amount with its currency
Fields
- currency? CurrencyCode - 3 letter alpha code for the ISO-4217 currency code, e.g. USD, AUD
- value? decimal -
xero.projects: ConnectionConfig
Provides a set of configurations for controlling the behaviours when communicating with a remote HTTP endpoint.
Fields
- auth BearerTokenConfig|OAuth2RefreshTokenGrantConfig - Configurations related to client authentication
- httpVersion HttpVersion(default http:HTTP_2_0) - The HTTP version understood by the client
- http1Settings ClientHttp1Settings(default {}) - Configurations related to HTTP/1.x protocol
- http2Settings ClientHttp2Settings(default {}) - Configurations related to HTTP/2 protocol
- timeout decimal(default 30) - The maximum time to wait (in seconds) for a response before closing the connection
- forwarded string(default "disable") - The choice of setting
forwarded/x-forwardedheader
- followRedirects? FollowRedirects - Configurations associated with Redirection
- poolConfig? PoolConfiguration - Configurations associated with request pooling
- cache CacheConfig(default {}) - HTTP caching related configurations
- compression Compression(default http:COMPRESSION_AUTO) - Specifies the way of handling compression (
accept-encoding) header
- circuitBreaker? CircuitBreakerConfig - Configurations associated with the behaviour of the Circuit Breaker
- retryConfig? RetryConfig - Configurations associated with retrying
- cookieConfig? CookieConfig - Configurations associated with cookies
- responseLimits ResponseLimitConfigs(default {}) - Configurations associated with inbound response size limits
- secureSocket? ClientSecureSocket - SSL/TLS-related options
- proxy? ProxyConfig - Proxy server related options
- socketConfig ClientSocketConfig(default {}) - Provides settings related to client socket configuration
- validation boolean(default true) - Enables the inbound payload validation functionality which provided by the constraint package. Enabled by default
- laxDataBinding boolean(default true) - Enables relaxed data binding on the client side. When enabled,
nilvalues are treated as optional, and absent fields are handled asnilabletypes. Enabled by default.
xero.projects: CreateProjectHeaders
Represents the Headers record for the operation: createProject
Fields
- xeroTenantId string - Xero identifier for Tenant
- idempotencyKey? string - This allows you to safely retry requests without the risk of duplicate processing. 128 character max
xero.projects: CreateTaskHeaders
Represents the Headers record for the operation: createTask
Fields
- xeroTenantId string - Xero identifier for Tenant
- idempotencyKey? string - This allows you to safely retry requests without the risk of duplicate processing. 128 character max
xero.projects: CreateTimeEntryHeaders
Represents the Headers record for the operation: createTimeEntry
Fields
- xeroTenantId string - Xero identifier for Tenant
- idempotencyKey? string - This allows you to safely retry requests without the risk of duplicate processing. 128 character max
xero.projects: DeleteTaskHeaders
Represents the Headers record for the operation: deleteTask
Fields
- xeroTenantId string - Xero identifier for Tenant
xero.projects: DeleteTimeEntryHeaders
Represents the Headers record for the operation: deleteTimeEntry
Fields
- xeroTenantId string - Xero identifier for Tenant
xero.projects: GetProjectHeaders
Represents the Headers record for the operation: getProject
Fields
- xeroTenantId string - Xero identifier for Tenant
xero.projects: GetTaskHeaders
Represents the Headers record for the operation: getTask
Fields
- xeroTenantId string - Xero identifier for Tenant
xero.projects: GetTimeEntryHeaders
Represents the Headers record for the operation: getTimeEntry
Fields
- xeroTenantId string - Xero identifier for Tenant
xero.projects: ListProjectsHeaders
Represents the Headers record for the operation: listProjects
Fields
- xeroTenantId string - Xero identifier for Tenant
xero.projects: ListProjectsQueries
Represents the Queries record for the operation: listProjects
Fields
- contactID? string - Filter for projects for a specific contact
- pageSize int(default 50) - 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
- projectIds? string[] - Search for all projects that match a comma separated list of projectIds
- page int(default 1) - set to 1 by default. The requested number of the page in paged response - Must be a number greater than 0
- states? string - Filter for projects in a particular state (INPROGRESS or CLOSED)
xero.projects: ListProjectUsersHeaders
Represents the Headers record for the operation: listProjectUsers
Fields
- xeroTenantId string - Xero identifier for Tenant
xero.projects: ListProjectUsersQueries
Represents the Queries record for the operation: listProjectUsers
Fields
- pageSize int(default 50) - 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
- page int(default 1) - set to 1 by default. The requested number of the page in paged response - Must be a number greater than 0
xero.projects: ListTasksHeaders
Represents the Headers record for the operation: listTasks
Fields
- xeroTenantId string - Xero identifier for Tenant
xero.projects: ListTasksQueries
Represents the Queries record for the operation: listTasks
Fields
- chargeType? ChargeType - Can be
TIME,FIXEDorNON_CHARGEABLE, defines how the task will be charged. UseTIMEwhen you want to charge per hour andFIXEDto charge as a fixed amount. If the task will not be charged useNON_CHARGEABLE
- pageSize? int - 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
- page? int - Set to 1 by default. The requested number of the page in paged response - Must be a number greater than 0
- taskIds? string - Search for all tasks that match a comma separated list of taskIds, i.e. GET https://.../tasks?taskIds={taskID},{taskID}
xero.projects: ListTimeEntriesHeaders
Represents the Headers record for the operation: listTimeEntries
Fields
- xeroTenantId string - Xero identifier for Tenant
xero.projects: ListTimeEntriesQueries
Represents the Queries record for the operation: listTimeEntries
Fields
- contactId? string - Finds all time entries for this contact identifier
- dateAfterUtc? string - ISO 8601 UTC date. Finds all time entries on or after this date filtered on the
dateUtcfield
- dateBeforeUtc? string - ISO 8601 UTC date. Finds all time entries on or before this date filtered on the
dateUtcfield
- pageSize? int - 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
- invoiceId? string - Finds all time entries for this invoice
- page? int - Set to 1 by default. The requested number of the page in paged response - Must be a number greater than 0
- userId? string - The xero user identifier of the person who logged time
- taskId? string - Identifier of the task that time entry is logged against
- states? string[] - Comma-separated list of states to find. Will find all time entries that are in the status of whatever is specified
- isChargeable? boolean - Finds all time entries which relate to tasks with the charge type
TIMEorFIXED
xero.projects: OAuth2RefreshTokenGrantConfig
OAuth2 Refresh Token Grant Configs
Fields
- Fields Included from *OAuth2RefreshTokenGrantConfig
- refreshUrl string(default "https://identity.xero.com/connect/token") - Refresh URL
xero.projects: Pagination
Pagination details of a paged response
Fields
- page? int - Set to 1 by default. The requested number of the page in paged response - Must be a number greater than 0.
- pageSize? int - 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.
- pageCount? int - Number of pages available
- itemCount? int - Number of items returned
xero.projects: Project
A Xero project with its invoicing and amount details
Fields
- expenseAmountInvoiced? Amount - Monetary amount with its currency
- depositApplied? Amount - Monetary amount with its currency
- taskAmountInvoiced? Amount - Monetary amount with its currency
- contactId? string - Identifier of the contact this project was created for
- taskAmountToBeInvoiced? Amount - Monetary amount with its currency
- expenseAmountToBeInvoiced? Amount - Monetary amount with its currency
- totalTaskAmount? Amount - Monetary amount with its currency
- projectAmountInvoiced? Amount - Monetary amount with its currency
- deadlineUtc? string - Deadline for the project. UTC Date Time in ISO-8601 format
- minutesToBeInvoiced? int - Minutes which have not been invoiced across all chargeable tasks in the project
- creditNoteAmount? Amount - Monetary amount with its currency
- name string - Name of the project
- estimateAmount? Amount - Monetary amount with its currency
- estimate? Amount - Monetary amount with its currency
- deposit? Amount - Monetary amount with its currency
- totalToBeInvoiced? Amount - Monetary amount with its currency
- totalExpenseAmount? Amount - Monetary amount with its currency
- projectId? string - Identifier of the project
- currencyCode? CurrencyCode - 3 letter alpha code for the ISO-4217 currency code, e.g. USD, AUD
- totalInvoiced? Amount - Monetary amount with its currency
- minutesLogged? int - A total of minutes logged against all tasks on the Project
- status? ProjectStatus - Status for project
xero.projects: ProjectCreateOrUpdate
Payload to create or update a project
Fields
- deadlineUtc? string - Deadline for the project. UTC Date Time in ISO-8601 format
- contactId? string - Identifier of the contact this project was created for
- name string - Name of the project
- estimateAmount? decimal -
xero.projects: ProjectList
Paged list of projects
Fields
- pagination? Pagination - Pagination details of a paged response
- items? Project[] -
xero.projects: ProjectPatch
Payload to change the status of a project
Fields
- status ProjectStatus - Status for project
xero.projects: ProjectUser
A user who can be assigned to project work
Fields
- name? string - Full name of the user
- userId? string - Identifier of the user of the project
- email? string - Email address of the user
xero.projects: ProjectUserList
Paged list of project users
Fields
- pagination? Pagination - Pagination details of a paged response
- items? ProjectUser[] -
xero.projects: Task
A task within a project with charge details
Fields
- fixedMinutes? int - Minutes logged against this task if its charge type is
FIXED
- chargeType? ChargeType - Can be
TIME,FIXEDorNON_CHARGEABLE, defines how the task will be charged. UseTIMEwhen you want to charge per hour andFIXEDto charge as a fixed amount. If the task will not be charged useNON_CHARGEABLE
- minutesInvoiced? int - Minutes on this task which have been invoiced
- totalAmount? Amount - Monetary amount with its currency
- amountInvoiced? Amount - Monetary amount with its currency
- rate? Amount - Monetary amount with its currency
- totalMinutes? int - Total minutes which have been logged against the task. Logged by assigning a time entry to a task
- minutesToBeInvoiced? int - Minutes on this task which have not been invoiced
- nonChargeableMinutes? int - Minutes logged against this task if its charge type is
NON_CHARGEABLE
- amountToBeInvoiced? Amount - Monetary amount with its currency
- name? string - Name of the task
- estimateMinutes? int - An estimated time to perform the task
- projectId? string - Identifier of the project task belongs to
- taskId? string - Identifier of the task
- status? "ACTIVE"|"INVOICED"|"LOCKED" - Status of the task. When a task of ChargeType is
FIXEDand the rate amount is invoiced the status will be set toINVOICEDand can't be modified. A task with ChargeType ofTIMEorNON_CHARGEABLEcannot have a status ofINVOICED. ALOCKEDstate indicates that the task is currently changing state (for example being invoiced) and can't be modified
xero.projects: TaskCreateOrUpdate
Payload to create or update a task
Fields
- rate Amount - Monetary amount with its currency
- name string - Name of the task. Max length 100 characters
- chargeType ChargeType - Can be
TIME,FIXEDorNON_CHARGEABLE, defines how the task will be charged. UseTIMEwhen you want to charge per hour andFIXEDto charge as a fixed amount. If the task will not be charged useNON_CHARGEABLE
- estimateMinutes? int - An estimated time to perform the task
xero.projects: TaskList
Paged list of tasks
Fields
- pagination? Pagination - Pagination details of a paged response
- items? Task[] -
xero.projects: TimeEntry
A time entry logged against a project task
Fields
- duration? int - The duration of logged minutes
- dateUtc? string - The date time that time entry is logged on. UTC Date Time in ISO-8601 format
- dateEnteredUtc? string - The date time that time entry is created. UTC Date Time in ISO-8601 format. By default it is set to server time
- timeEntryId? string - Identifier of the time entry
- description? string - A description of the time entry
- userId? string - The xero user identifier of the person who logged time
- projectId? string - Identifier of the project, that the task (which the time entry is logged against) belongs to
- taskId? string - Identifier of the task that time entry is logged against
- status? "ACTIVE"|"LOCKED"|"INVOICED" - Status of the time entry. By default a time entry is created with status of
ACTIVE. ALOCKEDstate indicates that the time entry is currently changing state (for example being invoiced). Updates are not allowed when in this state. It will have a status of INVOICED once it is invoiced
xero.projects: TimeEntryCreateOrUpdate
Payload to create or update a time entry
Fields
- duration int - Number of minutes to be logged. Duration is between 1 and 59940 inclusively
- dateUtc string - Date time entry is logged on. UTC Date Time in ISO-8601 format
- description? string - An optional description of the time entry, will be set to null if not provided during update
- userId string - The xero user identifier of the person logging the time
- taskId string - Identifier of the task that time entry is logged against
xero.projects: TimeEntryList
Paged list of time entries
Fields
- pagination? Pagination - Pagination details of a paged response
- items? TimeEntry[] -
xero.projects: UpdateProjectHeaders
Represents the Headers record for the operation: updateProject
Fields
- xeroTenantId string - Xero identifier for Tenant
- idempotencyKey? string - This allows you to safely retry requests without the risk of duplicate processing. 128 character max
xero.projects: UpdateProjectStatusHeaders
Represents the Headers record for the operation: updateProjectStatus
Fields
- xeroTenantId string - Xero identifier for Tenant
- idempotencyKey? string - This allows you to safely retry requests without the risk of duplicate processing. 128 character max
xero.projects: UpdateTaskHeaders
Represents the Headers record for the operation: updateTask
Fields
- xeroTenantId string - Xero identifier for Tenant
- idempotencyKey? string - This allows you to safely retry requests without the risk of duplicate processing. 128 character max
xero.projects: UpdateTimeEntryHeaders
Represents the Headers record for the operation: updateTimeEntry
Fields
- xeroTenantId string - Xero identifier for Tenant
- idempotencyKey? string - This allows you to safely retry requests without the risk of duplicate processing. 128 character max
Union types
xero.projects: CurrencyCode
CurrencyCode
3 letter alpha code for the ISO-4217 currency code, e.g. USD, AUD
xero.projects: ProjectStatus
ProjectStatus
Status for project
xero.projects: ChargeType
ChargeType
Can be TIME, FIXED or NON_CHARGEABLE, defines how the task will be charged. Use TIME when you want to charge per hour and FIXED to charge as a fixed amount. If the task will not be charged use NON_CHARGEABLE
Import
import ballerinax/xero.projects;Metadata
Released date: 1 day ago
Version: 2.0.0
License: Apache-2.0
Security
Direct vulnerabilities: No known direct vulnerabilities
Indirect vulnerabilities:
Checked on 2026-11-21 via OSV.dev
Compatibility
Platform: any
Ballerina version: 2201.12.0
GraalVM compatible: Yes
Pull count
Total: 45
Current verison: 1
Weekly downloads
Keywords
Vendor/Xero
Area/Finance & Accounting
Type/Connector
Contributors