Creates a PSA project.

POST /psa/projects

Group: PSA › Projects · Operation ID: createPsaProject

Creating a PSA project also creates its underlying timetracking project and team. teamLeadIds must contain at least one employee. The timetracking layer rejects a project with no team lead, and that failure currently comes back as an untyped server error rather than a typed diagnostic. The response contains only the new project's id. Read the record with GET psa/projects/:id.

Open in the interactive reference

Parameters

Name In Type Required Description
Api-Version header "v1" yes The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version v1.
Idempotency-Key header string no An opaque caller-chosen string (1-255 characters) that makes this request safe to retry. Repeating the same key with an identical request body replays the original response instead of re-executing - but only once that original request succeeded; a failed attempt re-executes on retry. Repeating the key with a different body is answered with 422. A key still in flight is answered with 409 - as is a key whose original request was interrupted before it finished, for a few minutes afterwards, until that attempt is presumed dead. A completed response stays replayable for 24 hours. The key is scoped to the caller, not to the action: reusing it for a different action is answered with 409 or 422 rather than treated independently. On read actions this header is ignored. On write actions that cannot offer the guarantee it is answered with 400 IDEMPOTENCY_NOT_SUPPORTED rather than silently ignored.

Request body

Required, application/json: createPsaProjectInput.

Field Type Required Description
name string yes The display name for the project.
startDate string (date) yes The project start date. Format YYYY-MM-DD.
endDate string (date) yes The project end date. Format YYYY-MM-DD.
teamStartDate string (date) no The team assignment start date. Defaults to startDate when omitted. Format YYYY-MM-DD.
teamEndDate string (date) no The team assignment end date. Defaults to endDate when omitted. Format YYYY-MM-DD.
teamLeadIds array of number yes The numeric identifiers of the employees to assign as project and team leads. At least one is required. There is no endpoint for them.
notifyProjectLeads boolean no Whether to notify the assigned project leads.
category string, one of "Billable", "Internal", "NonBillable" yes The project category. Accepted values: 'Billable', 'Internal', 'NonBillable'.
status string, one of "Tentative", "Planning", "PlanningDraft", "NotStarted", "InProgress", "Paused", "Completed", "Cancelled" yes The initial project status. Accepted values: 'Tentative', 'Planning', 'PlanningDraft', 'NotStarted', 'InProgress', 'Paused', 'Completed', 'Cancelled'.
currency string yes The project's default currency. Format ISO 4217, for example 'USD'.
budgetAmount string (decimal) no The project budget amount, in budgetCurrency.
budgetCurrency string no The currency of budgetAmount. Format ISO 4217, for example 'USD'. It should match the project's default currency.
departmentId number no The numeric identifier of the department to allocate the project to. GET departments/:id takes a UUID, so the number cannot be used to fetch the department.
customerId number no The numeric identifier of a customer to link directly to the project. It is ignored when salesArrangementId is set. GET accounting/customers/:id takes a UUID, so the number cannot be used to fetch the customer.
enforceActivityDateRange boolean no Whether time entries must fall within the project's startDate and endDate.
invoiced boolean no Whether to mark the project as invoiced. Defaults to false.
notes string no Free-form notes about the project.
opportunityId number no The numeric identifier of a CRM opportunity to link to the project. GET crm/opportunities/:id takes a UUID, so the number cannot be used to fetch the opportunity.
code string no A code for the project.
quoteId number no The numeric identifier of the CRM quote the project is created from. GET crm/quotes/:id takes a UUID, so the number cannot be used to fetch the quote.
salesArrangementId number no The numeric identifier of a sales arrangement that links the project to billing terms. When set, the direct customerId link is not persisted. There is no endpoint for it.
salesRepresentativeId number no The numeric identifier of the sales representative, an employee. There is no endpoint for it.
projectTypeId number no The numeric identifier of the project type. GET psa/project-types/:id takes a UUID, so the number cannot be used to fetch the project type.
externalLink string no A link to an external system for this project.
projectSettings object no The timetracking settings for the project. Created only when at least one setting is provided.
projectSettings.disableTimetrackingOnHolidays boolean no
projectSettings.disableTimetrackingOnWeekends boolean no
projectSettings.maxHoursPerDay string (decimal) no
projectSettings.maxHoursPerMonth string (decimal) no
projectSettings.maxHoursPerWeek string (decimal) no
projectSettings.billableHoursPerDay string (decimal) no
projectSettings.notifyNewMembers boolean no
projectSettings.requireNotes boolean no

Example:

{
  "name": "Acme Rollout",
  "startDate": "2026-09-01",
  "endDate": "2027-03-01",
  "teamStartDate": "2026-01-15",
  "teamEndDate": "2026-01-15",
  "teamLeadIds": [
    3845142
  ],
  "notifyProjectLeads": true,
  "category": "Billable",
  "status": "NotStarted",
  "currency": "USD",
  "budgetAmount": "19.99",
  "budgetCurrency": "<budgetCurrency>",
  "departmentId": 0,
  "customerId": 0,
  "enforceActivityDateRange": true,
  "invoiced": true,
  "notes": "<notes>",
  "opportunityId": 0,
  "code": "<code>",
  "quoteId": 0,
  "salesArrangementId": 0,
  "salesRepresentativeId": 0,
  "projectTypeId": 0,
  "externalLink": "<externalLink>",
  "projectSettings": {
    "disableTimetrackingOnHolidays": true,
    "disableTimetrackingOnWeekends": true,
    "maxHoursPerDay": "19.99",
    "maxHoursPerMonth": "19.99",
    "maxHoursPerWeek": "19.99",
    "billableHoursPerDay": "19.99",
    "notifyNewMembers": true,
    "requireNotes": true
  }
}

Response

200 Success

Under data (createPsaProjectOutput):

Field Type Required Description
id string yes The unique identifier for the created project.

Response headers

Errors

Code Status
IDEMPOTENCY_KEY_CONFLICT 409
IDEMPOTENCY_PAYLOAD_MISMATCH 422

Statuses