*REST API › Endpoint reference › Finance › Proformas*

# List proformas

> Returns the proformas of the account, cursor-paginated, with the same card as the detail read: number, lifecycle and commercial status, customer (id and name), source order, project, currency and amounts.

Lines, addresses and notes are not published. Filter by commercial status (pending, confirmed, cancelled), contact, source order, project and issue date. Sorted by issue date, most recent first. It shares scope with invoices because a proforma is the invoice that is not one yet.

`GET /api/v1/proformas` — scope `invoices:read`

Scope: `invoices:read` · 120/min · MCP: `filmo_proformas_list`

## Authorizations

Bearer API key with the scope below. `invoices:read`

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | No | Page size (1-500). Defaults to 50. = `50` |
| `cursor` | string | No | Opaque cursor of the page to return. Pass the value of `pagination.nextCursor` from the previous response; treat it as opaque. |
| `createdOn` | string | No | The creation date of the resource falls on this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `createdAfter` | string | No | The creation date of the resource is after this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `createdBefore` | string | No | The creation date of the resource is before this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `createdFrom` | string | No | The creation date of the resource is on or after this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `createdTo` | string | No | The creation date of the resource is on or before this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `updatedOn` | string | No | The last update date of the resource falls on this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `updatedAfter` | string | No | The last update date of the resource is after this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `updatedBefore` | string | No | The last update date of the resource is before this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `updatedFrom` | string | No | The last update date of the resource is on or after this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `updatedTo` | string | No | The last update date of the resource is on or before this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `sort` | string | No | Sort order: up to 3 comma-separated fields, each with a leading "-" for descending (e.g. "-updatedAt,name"). Sortable fields: createdAt, updatedAt, issueDate, proformaNumber. Defaults to "-issueDate". Ties are broken by id, so the order is stable across pages, and a cursor is bound to the sort it was issued with. |
| `operativeStatus` | string | No | Filter by commercial status: pending (awaiting an answer), confirmed (accepted by the customer) or cancelled (rejected or cancelled). `pending`, `confirmed`, `cancelled` |
| `operativeStatuses` | string[] | No | Filter by operativeStatus, as a list: repeat the parameter or separate the values with commas. Accepts up to 50 values and returns whatever matches any of them. `pending`, `confirmed`, `cancelled` |
| `contactId` | string | No | Filter by identifier of the contact the proforma is issued to. |
| `contactIds` | string[] | No | Filter by contactId, as a list: repeat the parameter or separate the values with commas. Accepts up to 50 values and returns whatever matches any of them. |
| `orderId` | string | No | Filter by identifier of the source order of the proforma. |
| `orderIds` | string[] | No | Filter by orderId, as a list: repeat the parameter or separate the values with commas. Accepts up to 50 values and returns whatever matches any of them. |
| `projectId` | string | No | Filter by identifier of the project linked to the proforma, directly or through its order. |
| `projectIds` | string[] | No | Filter by projectId, as a list: repeat the parameter or separate the values with commas. Accepts up to 50 values and returns whatever matches any of them. |
| `issueDateOn` | string | No | The proforma issue date falls on this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `issueDateAfter` | string | No | The proforma issue date is after this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `issueDateBefore` | string | No | The proforma issue date is before this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `issueDateFrom` | string | No | The proforma issue date is on or after this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `issueDateTo` | string | No | The proforma issue date is on or before this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset. |
| `includeTotal` | boolean | No | Set it to true to include `pagination.total`, the number of results that match the filters across all pages. Off by default. = `false` |

## Request examples

*List proformas*

**cURL**

```bash
curl https://app.filmo.io/api/v1/proformas \
  --header "Authorization: Bearer $FILMO_API_KEY"
```

**Node.js**

```javascript
fetch('https://app.filmo.io/api/v1/proformas', {
  headers: {
    Authorization: 'Bearer YOUR_FILMO_API_KEY'
  }
})
```

**Python**

```python
import requests

requests.get("https://app.filmo.io/api/v1/proformas",
    headers={
      "Authorization": "Bearer YOUR_FILMO_API_KEY"
    }
)
```

## Response

Response schema: `ProformaDto`

| Status | Description |
| --- | --- |
| 200 | Successful response. |
| 400 | Invalid request (validation_error): malformed query or body. `errors[]` lists every offending field with its stable code. |
| 401 | Authentication failed (unauthorized, api_key_invalid, api_key_revoked, api_key_expired, api_key_owner_inactive, api_key_owner_not_admin). |
| 403 | Not allowed (insufficient_scope: the API key does not have the required scope, named in `requiredScope`; forbidden: the owner of the key lacks the permission the operation requires). `insufficient_scope` is answered before the request counts against the rate limit, so it carries no `RateLimit-*` headers; `forbidden` does. |
| 429 | Rate limit exceeded (rate_limited): retry after `Retry-After` seconds; `RateLimit-*` says which quota ran out. |
| 500 | Internal error (internal_error). |

**200**

| Name | Type | Description |
| --- | --- | --- |
| `data` | object[] |  |
| `data.id` | string | Proforma identifier. |
| `data.proformaNumber` | string | Proforma number; null while it is a draft. |
| `data.status` | string | Document lifecycle status. |
| `data.operativeStatus` | string | Commercial status: pending (awaiting an answer), confirmed (accepted by the customer) or cancelled; null if not recorded. |
| `data.issueDate` | string<date-time> | Issue date in ISO 8601 UTC; null while it has none. |
| `data.currency` | string | Currency of the amounts, as an ISO 4217 code. |
| `data.contact` | object | Contact the proforma is issued to; null if not recorded. |
| `data.contact.id` | string | Contact identifier. |
| `data.contact.name` | string | Contact name. |
| `data.orderId` | string | Source order of the proforma; null if it does not come from one. |
| `data.orderNumber` | string | Number of that order; null if it does not come from one. |
| `data.projectId` | string | Project linked to the proforma; null if none. |
| `data.subTotal` | string | Subtotal before discounts and taxes, as a decimal string. |
| `data.discountTotal` | string | Total discounts, as a decimal string. |
| `data.taxesPrice` | string | Tax total, as a decimal string. |
| `data.netPrice` | string | Taxable base, as a decimal string. |
| `data.grossPrice` | string | Total including taxes, as a decimal string. |
| `data.totalPaid` | string | Advance payments received against the proforma, as a decimal string; null if none recorded. |
| `data.createdAt` | string<date-time> | Creation date in ISO 8601 UTC. |
| `data.updatedAt` | string<date-time> | Last modification date in ISO 8601 UTC. |
| `pagination` | object | Opaque-cursor pagination metadata. |
| `pagination.nextCursor` | string | Opaque cursor of the next page; null when there are no more results. Pass it as `cursor` in the next request. |
| `pagination.hasMore` | boolean | Whether more results exist beyond this page. |
| `pagination.total` | integer | Number of results matching the filters across all pages. Present only when the request sets `includeTotal=true`. |
| `meta` | object | Additional information about the response. |
| `meta.warnings` | object[] | Lifecycle warnings; present only when the operation is deprecated. |
| `meta.warnings.code` | string | Stable warning code. `deprecated` |
| `meta.warnings.message` | string | For people: what is deprecated, until when, and what to use. |
| `meta.warnings.sunset` | string | Day (YYYY-MM-DD) the operation stops being served. |
| `meta.warnings.replacement` | string | `operationId` of the operation to use instead, or null if there is none. |
| `meta.warnings.link` | string | Where the deprecation is documented (the changelog). |

*Example response · 200*

```json
{
  "data": [
    {
      "id": "proforma_9f3a2b",
      "proformaNumber": "2026-0001",
      "status": "Example status",
      "operativeStatus": "Example operative status",
      "issueDate": "2026-09-01T08:00:00.000Z",
      "currency": "EUR",
      "contact": {
        "id": "contact_9f3a2b",
        "name": "Example contact"
      },
      "orderId": "order_9f3a2b",
      "orderNumber": "2026-0001",
      "projectId": "project_9f3a2b",
      "subTotal": "120.00",
      "discountTotal": "120.00",
      "taxesPrice": "120.00",
      "netPrice": "120.00",
      "grossPrice": "120.00",
      "totalPaid": "120.00",
      "createdAt": "2026-09-01T08:00:00.000Z",
      "updatedAt": "2026-09-01T08:00:00.000Z"
    }
  ],
  "pagination": {
    "nextCursor": "eyJvIjoyMH0",
    "hasMore": true,
    "total": 1
  }
}
```

## Errors

| Status | Codes | Meaning |
| --- | --- | --- |
| 400 | `validation_error` | Malformed query or body. `errors[]` lists every offending field with its stable code. |

## Deprecation

This operation is not deprecated. Deprecations are announced with a Deprecation header and a sunset date.

---

Canonical URL: https://docs.filmo.io/rest-api/endpoint-reference/proformas/list-proformas  
Last updated: 2026-10-25