> ## Documentation Index
> Fetch the complete documentation index at: https://docs.royaltyport.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Statements

> List and retrieve royalty statements with processing status and metadata.

## List Statements

Returns a paginated list of statements for a project.

### Request

```
GET /v1/statements
```

### Query Parameters

| Parameter   | Type    | Required | Default | Description                        |
| ----------- | ------- | -------- | ------- | ---------------------------------- |
| `projectId` | UUID    | Yes      | —       | The project to list statements for |
| `page`      | integer | No       | `1`     | Page number (1-indexed)            |
| `perPage`   | integer | No       | `20`    | Items per page (1–100)             |

### Headers

| Header          | Required | Description                                                |
| --------------- | -------- | ---------------------------------------------------------- |
| `Authorization` | Yes      | `Bearer <token>` — must be scoped to the requested project |

### Response

```json theme={null}
{
  "data": {
    "items": [
      {
        "id": 1234,
        "file_name": "Q1-2025-royalties.xlsx",
        "file_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
        "file_size": 524288,
        "statement_name": "Q1 2025 Royalties",
        "statement_type": "royalty",
        "statement_category": "recording",
        "statement_producer": "Sony Music Entertainment",
        "processing_status": "completed",
        "upload_status": "completed",
        "approval_status": "approved",
        "has_revenues": true,
        "has_costs": false,
        "has_summary": true,
        "currency_transaction": "USD",
        "currency_royalty": "EUR",
        "entity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "created_at": "2025-03-01T12:00:00Z",
        "processed_at": "2025-03-01T12:05:00Z"
      }
    ],
    "total_count": 42,
    "page": 1,
    "per_page": 20
  }
}
```

<Note>
  Null fields are stripped from the response. For example, if a statement has not been processed yet, `processed_at`, `statement_name`, and other derived fields will be absent.
</Note>

### Errors

| Status | Description                                     |
| ------ | ----------------------------------------------- |
| `400`  | Missing `projectId` or invalid query parameters |
| `403`  | Token is not scoped to the requested project    |

### Example

```bash theme={null}
curl "https://api.royaltyport.com/v1/statements?projectId=a1b2c3d4-...&page=1&perPage=10" \
  -H "Authorization: Bearer rp_your_token_here"
```

***

## Get Statement

Returns a single statement by ID with full metadata.

### Request

```
GET /v1/statements/{statement_id}
```

### Path Parameters

| Parameter      | Type    | Required | Description      |
| -------------- | ------- | -------- | ---------------- |
| `statement_id` | integer | Yes      | The statement ID |

### Query Parameters

| Parameter   | Type | Required | Default | Description                          |
| ----------- | ---- | -------- | ------- | ------------------------------------ |
| `projectId` | UUID | Yes      | —       | The project the statement belongs to |

### Headers

| Header          | Required | Description                                                |
| --------------- | -------- | ---------------------------------------------------------- |
| `Authorization` | Yes      | `Bearer <token>` — must be scoped to the requested project |

### Response

```json theme={null}
{
  "data": {
    "id": 1234,
    "file_name": "Q1-2025-royalties.xlsx",
    "file_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
    "file_size": 524288,
    "statement_name": "Q1 2025 Royalties",
    "statement_desc": "Quarterly royalty report for recording revenues",
    "statement_type": "royalty",
    "statement_category": "recording",
    "statement_subtype": "mechanical",
    "statement_producer": "Sony Music Entertainment",
    "statement_version": "1.0",
    "processing_status": "completed",
    "upload_status": "completed",
    "approval_status": "approved",
    "has_revenues": true,
    "has_costs": false,
    "has_summary": true,
    "has_summary_lines": true,
    "currency_transaction": "USD",
    "currency_royalty": "EUR",
    "entity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "created_at": "2025-03-01T12:00:00Z",
    "processed_at": "2025-03-01T12:05:00Z",
    "modified_at": "2025-03-02T09:30:00Z"
  }
}
```

<Note>
  The get endpoint returns additional fields not present in the list response: `statement_desc`, `statement_subtype`, `statement_version`, `has_summary_lines`, and `modified_at`.
</Note>

### Errors

| Status | Description                                     |
| ------ | ----------------------------------------------- |
| `400`  | Missing `projectId` or invalid query parameters |
| `403`  | Token is not scoped to the requested project    |
| `404`  | Statement not found                             |

### Example

```bash theme={null}
curl "https://api.royaltyport.com/v1/statements/1234?projectId=a1b2c3d4-..." \
  -H "Authorization: Bearer rp_your_token_here"
```