Projects

Overview

Projects allow entities to aggregate and track payables and receivables 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.

Roles and permissions

To use the /projects* endpoints with an entity user token, this entity user must have a role with the project permission.

If using a partner-level token, no special permissions are needed.

Create a project

To create a new project, call the POST /projects endpoint:

1
curl -X POST 'https://api.sandbox.monite.com/v1/projects' \
2
     -H 'X-Monite-Version: 2024-01-31' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN' \
5
     -H 'Content-Type: application/json' \
6
     -d '{
7
        "code": "6pJ8Grew3zvtVFkZWDYY",
8
        "color": "#ABCDEF",
9
        "description": "Project description",
10
        "end_date": "2025-09-09",
11
        "name": "Marketing",
12
        "parent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
13
        "partner_metadata": {},
14
        "start_date": "2024-09-09",
15
        "tag_ids": []
16
      }

The successful response contains all the information about the project:

1
{
2
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
3
  "created_at": "2024-09-09T09:48:11.301Z",
4
  "updated_at": "2024-09-09T09:48:11.301Z",
5
  "code": "6pJ8Grew3zvtVFkZWDYY",
6
  "color": "#ABCDEF",
7
  "created_by_entity_user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
8
  "description": "Project description",
9
  "end_date": "2025-09-09",
10
  "entity_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
11
  "name": "Marketing",
12
  "parent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
13
  "partner_metadata": {},
14
  "start_date": "2024-09-09",
15
  "tags": []
16
}

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, call POST /payables informing the specific project_id in the payload.
• To create a receivable, call 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 to a project, call PATCH /payables/{payable_id} informing the specific project_id in the payload.
• To assign an existing receivable to a project, call PATCH /receivables/{receivable_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} for listing all payables of a specific project.
• /receivables?project_id={project_id} for listing all receivables of a specific project.

Update a project

To update specific information on an existing project, call PATCH /projects/{project_id} endpoint. These are the fields that can be updated:

• name
• description
• start_date
• end_date
• code
• color
• tag_ids

1
curl -X PATCH 'https://api.sandbox.monite.com/v1/projects/{project_id}' \
2
     -H 'X-Monite-Version: 2024-01-31' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN' \
5
     -H 'Content-Type: application/json' \
6
     -d '{
7
        "start_date": "2024-08-25",
8
        "end_date": "2024-10-28"
9
    }

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

1
{
2
    "id": "12345678-1234-1234-1234-123456789012",
3
    "name": "Project name",
4
    "description": "Project description",
5
    "start_date": "2024-08-25",
6
    "end_date": "2024-10-28",
7
    "code": "ABC",
8
    "color": "#ABCDEF",
9
    "created_at": "2024-07-31T11:55:37.866Z",
10
    "updated_at": "2024-07-31T11:55:37.866Z",
11
    "created_by_entity_user_id": "12345678-1234-1234-1234-123456789012",
12
    "tags": [],
13
    "partner_metadata": {
14
      "key":"value",
15
      "integer":123,
16
      "float": 0.22
17
    }
18
}

List all projects

To get information about all projects associated with the specified entity, call the GET /projects endpoint.

Retrieve a project

To get information about a specific project, call the GET /projects/{project_id} endpoint.

Delete a project

To delete an existing project, call the DELETE /projects/{project_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.