Statements

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)
`stagingIds`	string	No	—	Comma-separated list of staging IDs to filter by (e.g. `101,102,103`)
`processingStatus`	string	No	—	Filter by processing status. One of `processed`, `processing`, `errors`, `failed`, `warnings`.

Headers

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

Response

{
  "data": {
    "items": [
      {
        "id": 1234,
        "staging_id": 101,
        "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
  }
}

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.

Errors

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

Example

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
`detailed`	string	No	`false`	Set to `true` to attach the statement’s full detailed export. Adds a `detailed` object (or `null`) plus a `detailed_error` reason field to the response; the statement itself is still returned even if the export fails.

Headers

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

Response

{
  "data": {
    "id": 1234,
    "staging_id": 101,
    "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",
    "accounting_period": "Q1 2025",
    "financials": {
      "sections": 3,
      "payee": "Adele",
      "payer": "Sony Music Entertainment",
      "currency": "EUR",
      "period": "Q1 2025",
      "opening_balance": 0,
      "licensee_revenue": 125000.50,
      "licensor_revenue": 42500.75,
      "costs_total": 5000.00,
      "deductions_total": 1200.00,
      "advances_total": 0,
      "reserves_held": 3000.00,
      "closing_balance": 33300.75,
      "amount_payable": 33300.75
    }
  }
}

The get endpoint returns additional fields not present in the list response: statement_desc, statement_subtype, statement_version, has_summary_lines, modified_at, accounting_period, and the always-present financials object (aggregated from the statement’s summary sections; each numeric field defaults to 0 and string fields to "" when there is no summary data).

Errors

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

Example

curl "https://api.royaltyport.com/v1/statements/1234?projectId=a1b2c3d4-..." \
  -H "Authorization: Bearer rp_your_token_here"

Getting Started

REST API

List Statements

Request

Query Parameters

Headers

Response

Errors

Example

Get Statement

Request

Path Parameters

Query Parameters

Headers

Response

Errors

Example

​List Statements

​Request

​Query Parameters

​Headers

​Response

​Errors

​Example

​Get Statement

​Request

​Path Parameters

​Query Parameters

​Headers

​Response

​Errors

​Example

List Statements

Request

Query Parameters

Headers

Response

Errors

Example

Get Statement

Request

Path Parameters

Query Parameters

Headers

Response

Errors

Example