Projects

Purpose

Returns a paginated list of projects, with the core fields needed to identify a project and know its current state.

Filters can be combined freely: every filter you send is applied together, and a project is returned only when it satisfies all of them. Projects can be looked up by their own id or reference, and by the customer they belong to.

🔎 Query parameters

All filters are optional and can be combined. Sending none returns the paginated list of all projects, ordered by id descending.

Filters sent as empty or whitespace-only strings are ignored, exactly as if they had not been sent. Unrecognized query parameters are ignored.

Example Requests

Retrieve every project of a customer, using the reference you already hold in your own system:

GET /api/integration/project?customerReference=EXT-CUSTOMER-REF-001

Retrieve a single project by its reference:

GET /api/integration/project?reference=EXT-PROJECT-REF-001

Combine filters to confirm that a project belongs to a specific customer:

GET /api/integration/project?reference=EXT-PROJECT-REF-001&customerId=2001

Paginate the full project list:

GET /api/integration/project?pageSize=25&pageNumber=2

Response Example

{
  "data": [
    {
      "id": 4821,
      "reference": "EXT-PROJECT-REF-001",
      "name": "Instalación red eléctrica - Sucursal Centro",
      "status": "in_execution",
      "customer": {
        "id": 2001,
        "reference": "EXT-CUSTOMER-REF-001"
      },
      "startDate": "2026-07-14T00:00:00.000Z",
      "endDate": null,
      "createdDate": "2026-07-02T13:45:21.000Z"
    },
    {
      "id": 4790,
      "reference": null,
      "name": "Mantención preventiva - Bodega Norte",
      "status": "done",
      "customer": {
        "id": 2001,
        "reference": "EXT-CUSTOMER-REF-001"
      },
      "startDate": "2026-05-02T00:00:00.000Z",
      "endDate": "2026-06-20T00:00:00.000Z",
      "createdDate": "2026-04-28T09:12:03.000Z"
    }
  ],
  "metadata": {
    "count": 7,
    "pageNumber": 1,
    "pageSize": 10,
    "totalPages": 1
  }
}

Project item (data[])

Customer (data[].customer)

Pagination (metadata)

Error Responses

When the filters match no projects, the request still succeeds: data is [] and metadata.count is 0.

Business Rules & Constraints

Combining filters

Every filter present in the request is applied together, and only projects satisfying all of them are returned.

Filters come in two pairs pointing at the same record through different fields: id and reference identify the project itself, while customerId and customerReference identify its customer. Sending both members of a pair is a valid way to confirm that a record matches on both fields.

Pointing two filters at different records is not an error. The request succeeds and returns an empty page, because no single project satisfies both conditions.

Filtering by customer

customerId and customerReference return every project belonging to the matching customer, paginated like any other query. A customer with no projects yields an empty page.

Only the customer assigned to the project is considered.

Pagination

• pageNumber is 1-based: the first page is 1.

• Default pageSize is 10, maximum is 50.

• count reflects all projects matching the filters, not only those on the current page.

• Results are always ordered by id descending, so the most recently created projects appear first.

Project status

status reflects the current state of the project:

Returned data

• Timestamps use ISO 8601 in UTC.