> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.monite.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.monite.com/_mcp/server.

# Projects

## Overview

Projects allow entities to aggregate and track [payables](../accounts-payable/payables/index), [purchase orders](../accounts-payable/purchase-orders), and [receivables](../accounts-receivable/index) under the same work scope, improving spending control, resource allocation, timelines, and communication. The characteristics of the project includes start and end dates, identifier code, color, tags, and metadata.

PDF receivables display the associated project name in the document header:

![Project name in a PDF invoice](/_fern-img/d3a8811f2f672d02ec3b5b381c99348875cf1a9b181c4f1420ca72ad7022a645.webp)

## Roles and permissions \[#permissions]

To use the `/projects*` endpoints with an [entity user token](../entities/users#get-entity-user-token), this entity user must have a [role](../entities/users#create-role) with the `project` permission.

If using a [partner-level token](../get-started/credentials#generate-partner-token), no special permissions are needed.

## Create a project

To create a new project, call the [`POST /projects`](/api/projects/post-projects) endpoint:

```sh
curl -X POST 'https://api.sandbox.monite.com/v1/projects' \
     -H 'X-Monite-Version: 2024-05-25' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
        "code": "6pJ8Grew3zvtVFkZWDYY",
        "color": "#ABCDEF",
        "description": "Project description",
        "end_date": "2025-09-09",
        "name": "Marketing",
        "parent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "partner_metadata": {},
        "start_date": "2024-09-09",
        "tag_ids": []
      }
```

The successful response contains all the information about the project:

```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2024-09-09T09:48:11.301Z",
  "updated_at": "2024-09-09T09:48:11.301Z",
  "code": "6pJ8Grew3zvtVFkZWDYY",
  "color": "#ABCDEF",
  "created_by_entity_user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "description": "Project description",
  "end_date": "2025-09-09",
  "entity_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Marketing",
  "parent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "partner_metadata": {},
  "start_date": "2024-09-09",
  "tags": []
}
```

### Create a document within a project

It is possible to create a new payable or receivable directly connected to a project.

* To [create a payable](../accounts-payable/payables/collect), call [`POST /payables`](/api/payables/post-payables) informing the specific `project_id` in the payload.
* To [create a purchase order](../accounts-payable/purchase-orders), call [`POST /payable_purchase_orders`](/api/purchase-orders/post-payable-purchase-orders) informing the specific `project_id` in the payload.
* To [create a receivable](../accounts-receivable/invoices/create), call [`POST /receivables`](/api/receivables/post-receivables) informing the specific `project_id` in the payload.

### Assign existing documents to a project

You can also assign an already existing payable or receivable to a project.

* To [assign an existing payable](../accounts-payable/payables/manage#update-a-payable) to a project, call [`PATCH /payables/{payable_id}`](/api/payables/patch-payables-id) informing the specific `project_id` in the payload.
* To [assign an existing purchase order](../accounts-payable/purchase-orders#edit) to a project, call [`PATCH /payable_purchase_orders/{purchase_order_id}`](/api/purchase-orders/patch-payable-purchase-orders-id) informing the specific `project_id` in the payload.
* To [assign an existing receivable](../accounts-receivable/invoices/manage#update-an-invoice) to a project, call [`PATCH /receivables/{receivable_id}`](/api/receivables/patch-receivables-id) informing the specific `project_id` in the payload.

### List all documents of a project

To list all documents of a specific project, send a `GET` request to:

* [`/payables?project_id={project_id}`](/api/payables/get-payables) for listing all payables of a specific project.
* [`/payable_purchase_orders?project_id={project_id}`](/api/purchase-orders/get-payable-purchase-orders) for listing all purchase orders of a specific project.
* [`/receivables?project_id={project_id}`](/api/receivables/get-receivables) for listing all receivables of a specific project.

## Update a project

To update specific information on an existing project, call [`PATCH /projects/{project_id}`](/api/projects/patch-projects-id) endpoint. These are the fields that can be updated:

* `name`
* `description`
* `start_date`
* `end_date`
* `code`
* `color`
* `tag_ids`

```sh
curl -X PATCH 'https://api.sandbox.monite.com/v1/projects/{project_id}' \
     -H 'X-Monite-Version: 2024-05-25' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
        "start_date": "2024-08-25",
        "end_date": "2024-10-28"
    }
```

The successful response contains all the information about the project, including the updated fields.

```json
{
    "id": "12345678-1234-1234-1234-123456789012",
    "name": "Project name",
    "description": "Project description",
    "start_date": "2024-08-25",
    "end_date": "2024-10-28",
    "code": "ABC",
    "color": "#ABCDEF",
    "created_at": "2024-07-31T11:55:37.866Z",
    "updated_at": "2024-07-31T11:55:37.866Z",
    "created_by_entity_user_id": "12345678-1234-1234-1234-123456789012",
    "tags": [],
    "partner_metadata": {
      "key":"value",
      "integer":123,
      "float": 0.22
    }
}
```

## List all projects

To get information about all projects associated with the specified entity, call the [`GET /projects`](/api/projects/get-projects) endpoint.

## Retrieve a project

To get information about a specific project, call the [`GET /projects/{project_id}`](/api/projects/get-projects-id) endpoint.

## Delete a project

To delete an existing project, call the [`DELETE /projects/{project_id}`](/api/projects/delete-projects-id) endpoint. The system will check for any associated payables or receivables. If any are found, a `204 - No Content` response will be returned, and the project will **not** be deleted.