*REST API › Objects › Rentals*

# Project

> The project, as returned by the API.

A project that groups orders and work for a contact, with its dates, type, location and the identifiers of its orders. Projects use the tenancy inherited from the parent account, so a billing account also sees the projects of its parent. [`externalReference`](https://docs.filmo.io/rest-api/objects/project#response-externalReference) is writable, so it can hold your own key. Archive or restore a project with [`PUT /api/v1/projects/{projectId}/archive`](https://docs.filmo.io/rest-api/endpoint-reference/projects/archive-or-restore-a-project), and link orders to it with [`POST /api/v1/projects/{projectId}/orders/{orderId}`](https://docs.filmo.io/rest-api/endpoint-reference/projects/link-an-order-to-a-project).

Schemas: `ProjectDto`, `ProjectDetailDto`

## Attributes

| Name | Type | Description |
| --- | --- | --- |
| `id` | string | Unique project identifier. |
| `projectNumber` | string | Human-readable project number; null if not numbered. |
| `name` | string | Project name. |
| `color` | string | Color associated with the project (for the UI); null if none. |
| `externalReference` | string | External reference of the project (for example, from the customer system); null if not recorded. |
| `projectTypeId` | string | Project type identifier; null if the project has no type. |
| `projectType` | object | Compact reference to the project type; null if none. |
| `projectType.id` | string | Unique project type identifier. |
| `projectType.name` | string | Project type name. |
| `projectType.color` | string | Color associated with the project type (for the UI); null if none. |
| `contact` | object | Compact reference to the project contact; null if none. |
| `contact.id` | string | Unique contact identifier. |
| `contact.name` | string | Contact name. |
| `location` | object | Project location; its inner fields are null when not recorded. |
| `location.name` | string | Name of the place/location; null if not recorded. |
| `location.address` | string | Address of the location; null if not recorded. |
| `location.city` | string | City of the location; null if not recorded. |
| `location.postalCode` | string | Postal code of the location; null if not recorded. |
| `location.province` | string | Province or region of the location; null if not recorded. |
| `location.country` | string | Country of the location; null if not recorded. |
| `location.lat` | number | Latitude of the location; null if not recorded. |
| `location.lng` | number | Longitude of the location; null if not recorded. |
| `startDate` | string<date-time> | Project start date in ISO 8601 with offset. |
| `endDate` | string<date-time> | Project end date in ISO 8601 with offset. |
| `status` | string | Project status: draft, budgeted, confirmed, in_progress, invoiced, completed, cancelled or archived. `archived` is a LEGACY status that appears in old data; the current archived state is expressed by the `archived` boolean of this same DTO. `draft`, `budgeted`, `confirmed`, `in_progress`, `invoiced`, `completed`, `cancelled`, `archived` |
| `archived` | boolean | Whether the project is archived. |
| `orderIds` | string[] | Identifiers of the project orders. Order details are obtained from [`GET /api/v1/orders`](https://docs.filmo.io/rest-api/endpoint-reference/orders/list-orders)?projectId=. |
| `totalOrders` | integer | Total number of orders in the project (equals orderIds.length). |
| `tags` | object[] | Tags attached to the project, with their identifier and name. |
| `tags.id` | string | Unique identifier of the tag. |
| `tags.name` | string | Tag name. |
| `customFields` | object<string, any> | Custom field values by custom field identifier; the definitions are in `/api/v1/custom-fields`. |
| `source` | string | Source the project was created from; null if not recorded. |
| `createdAt` | string<date-time> | Creation date in ISO 8601 with offset. |
| `updatedAt` | string<date-time> | Last update date in ISO 8601 with offset. |

## Values

| Field | Values |
| --- | --- |
| `status` | `draft`, `budgeted`, `confirmed`, `in_progress`, `invoiced`, `completed`, `cancelled`, `archived` |

## Example

*Project · Generated from the schema*

```json
{
  "id": "id_8f2a1c",
  "projectNumber": "string",
  "name": "Example",
  "color": "string",
  "externalReference": "string",
  "projectTypeId": "string",
  "projectType": {
    "id": "id_8f2a1c",
    "name": "Example",
    "color": "string"
  },
  "contact": {
    "id": "id_8f2a1c",
    "name": "Example"
  },
  "location": {
    "name": "Example",
    "address": "string",
    "city": "string",
    "postalCode": "string",
    "province": "string",
    "country": "ES",
    "lat": 1,
    "lng": 1
  },
  "startDate": "2026-09-01T08:00:00Z",
  "endDate": "2026-09-01T08:00:00Z",
  "status": "draft",
  "archived": true,
  "orderIds": [
    "string"
  ],
  "totalOrders": 1,
  "tags": [
    {
      "id": "id_8f2a1c",
      "name": "Example"
    }
  ],
  "customFields": {
    "key": "string"
  },
  "source": "string",
  "createdAt": "2026-09-01T08:00:00Z",
  "updatedAt": "2026-09-01T08:00:00Z"
}
```

## Returned by

- [`GET /api/v1/projects`](https://docs.filmo.io/rest-api/endpoint-reference/projects/list-projects) — List projects
- [`GET /api/v1/projects/{projectId}`](https://docs.filmo.io/rest-api/endpoint-reference/projects/get-a-project) — Get a project

## Modified by

- [`POST /api/v1/projects`](https://docs.filmo.io/rest-api/endpoint-reference/projects/create-a-project) — Create a project
- [`PATCH /api/v1/projects/{projectId}`](https://docs.filmo.io/rest-api/endpoint-reference/projects/update-a-project) — Update a project
- [`POST /api/v1/projects/{projectId}/orders/{orderId}`](https://docs.filmo.io/rest-api/endpoint-reference/projects/link-an-order-to-a-project) — Link an order to a project
- [`DELETE /api/v1/projects/{projectId}/orders/{orderId}`](https://docs.filmo.io/rest-api/endpoint-reference/projects/unlink-an-order-from-a-project) — Unlink an order from a project

---

Canonical URL: https://docs.filmo.io/rest-api/objects/project  
Last updated: 2026-10-25