# Create a project

Operation ID: `createPsaProject`

Group: PSA › Projects

[Open in the interactive reference](https://docs.api.lensing.ai/lensing/v1/endpoints/createPsaProject)

`POST /psa/projects`

Retry-safe: A write that accepts Idempotency-Key: repeating a request with the same key replays the stored answer instead of executing twice.

Creates a project. The request also creates the project's time-tracking project and its team. Each employee in teamLeadIds is also given the PSA manager permission role.

The response contains only the new project's id. Read the project with GET psa/projects/:id.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Api-Version` | header | string · 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. Example: `"Acme Rollout"`. |
| `startDate` | date | yes | The project start date. Format YYYY-MM-DD. Example: `"2026-09-01"`. |
| `endDate` | date | yes | The project end date. Format YYYY-MM-DD. Example: `"2027-03-01"`. |
| `teamStartDate` | date | no | The team assignment start date. Defaults to startDate when omitted. Format YYYY-MM-DD. |
| `teamEndDate` | date | no | The team assignment end date. Defaults to endDate when omitted. Format YYYY-MM-DD. |
| `teamLeadIds` | array<number> | yes | The numeric identifiers of the employees to assign as project and team leads. You must send the list, but it can be empty. There is no endpoint for them. Example: `[3845142]`. |
| `notifyProjectLeads` | boolean | no | Whether to notify the assigned project leads. |
| `category` | any | yes | The project category. Accepted values: 'Billable', 'Internal', 'NonBillable'. One of: `"Billable"`, `"Internal"`, `"NonBillable"`. Example: `"Billable"`. |
| `status` | any | yes | The initial project status. Accepted values: 'Tentative', 'Planning', 'PlanningDraft', 'NotStarted', 'InProgress', 'Paused', 'Completed', 'Cancelled'. One of: `"Tentative"`, `"Planning"`, `"PlanningDraft"`, `"NotStarted"`, `"InProgress"`, `"Paused"`, `"Completed"`, `"Cancelled"`. Example: `"NotStarted"`. |
| `currency` | string | yes | The project's default currency. Format ISO 4217, for example 'USD'. Example: `"USD"`. |
| `budgetAmount` | 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 people/departments/:id takes a UUID, so the number cannot be used to fetch the department. |
| `entityId` | number | no | The numeric identifier of the legal entity the project belongs to. When salesArrangementId is set, it defaults to the sales arrangement's entity, and a different value fails with the message 'The project's entity must match the entity of its sales arrangement'. GET base/entities lists entities by UUID, so the number cannot be used to look the entity up there. |
| `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` | decimal | no |  |
| `projectSettings.maxHoursPerMonth` | decimal | no |  |
| `projectSettings.maxHoursPerWeek` | decimal | no |  |
| `projectSettings.billableHoursPerDay` | decimal | no |  |
| `projectSettings.notifyNewMembers` | boolean | no |  |
| `projectSettings.requireNotes` | boolean | no |  |

```json
{
  "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,
  "entityId": 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. Example: `"3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45"`. |

```json
{
  "data": {
    "id": "3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45"
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}
```

## Response headers

- `Idempotency-Replayed` — Present and `true` only when this response replays a previously stored one for the same Idempotency-Key, rather than reflecting a live execution. Absent on a live response - never sent as `false`.

## Errors

| Code | Status |
| --- | --- |
| `IDEMPOTENCY_KEY_CONFLICT` | 409 |
| `IDEMPOTENCY_PAYLOAD_MISMATCH` | 422 |

## Statuses

- `400` — Invalid request or business failure
- `401` — The request carries no valid access token.
- `403` — Not authorized
- `404` — Not found
- `409` — The Idempotency-Key is still being processed by another request.
- `422` — The Idempotency-Key was already used with a different request payload.
- `429` — Too many requests from this client address. The response has no body and no `Retry-After` header.
- `500` — Internal server error