List Contracts
Returns a paginated list of contracts for a project. Use the includes parameter to embed sub-resource data inline.
Request
Query Parameters
| Parameter | Type | Required | Default | Description |
|---|
projectId | UUID | Yes | — | The project to list contracts for |
page | integer | No | 1 | Page number (1-indexed) |
perPage | integer | No | 20 | Items per page (1–100) |
includes | string | No | — | Comma-separated list of sub-resources to embed |
| Header | Required | Description |
|---|
Authorization | Yes | Bearer <token> — must be scoped to the requested project |
Sub-Resource Includes
Pass a comma-separated list of sub-resource names in the includes parameter to embed related data in each contract object:
| Include | Description |
|---|
entities | Entities linked to the contract |
artists | Artists linked to the contract |
writers | Writers linked to the contract |
royalties | Royalty terms extracted from the contract |
splits | Revenue split information |
costs | Cost provisions |
compensations | Compensation terms |
dates | Key dates (effective, termination, etc.) |
accounting-periods | Accounting period definitions |
types | Contract type classifications |
signatures | Signature information |
control-areas | Control area definitions |
creative-approvals | Creative approval clauses |
balances | Balance provisions and terms |
recordings | Recordings linked to the contract |
compositions | Compositions linked to the contract |
Response
{
"data": [
{
"id": "contract-123",
"name": "Distribution Agreement",
"project_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"created_at": "2025-03-01T12:00:00Z",
"entities": [
{ "id": "ent-1", "name": "Sony Music Entertainment" }
],
"royalties": [
{ "id": "roy-1", "rate": "18%", "type": "mechanical" }
]
}
]
}
Sub-resource keys only appear in the response when requested via includes. Without includes, only the base contract fields are returned.
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/contracts?projectId=a1b2c3d4-...&page=1&perPage=10&includes=entities,royalties" \
-H "Authorization: Bearer rp_your_token_here"
Get Contract
Returns a single contract by ID, with optional sub-resource includes.
Request
GET /v1/contracts/{contract_id}
Path Parameters
| Parameter | Type | Required | Description |
|---|
contract_id | string | Yes | The contract ID |
Query Parameters
| Parameter | Type | Required | Default | Description |
|---|
projectId | UUID | Yes | — | The project the contract belongs to |
includes | string | No | — | Comma-separated list of sub-resources to embed (see table above) |
| Header | Required | Description |
|---|
Authorization | Yes | Bearer <token> — must be scoped to the requested project |
Response
{
"data": {
"id": "contract-123",
"name": "Distribution Agreement",
"project_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"created_at": "2025-03-01T12:00:00Z",
"entities": [
{ "id": "ent-1", "name": "Sony Music Entertainment" }
]
}
}
Errors
| Status | Description |
|---|
400 | Missing projectId or invalid query parameters |
403 | Token is not scoped to the requested project |
404 | Contract not found |
Example
curl "https://api.royaltyport.com/v1/contracts/contract-123?projectId=a1b2c3d4-...&includes=entities,artists,royalties" \
-H "Authorization: Bearer rp_your_token_here"
