List Relations
Returns a paginated list of root relations for a project. Relations represent contacts (people and companies) from the CRM, extracted from contract documents and de-duplicated via merging.
Request
Query Parameters
| Parameter | Type | Required | Default | Description |
|---|
projectId | UUID | Yes | — | The project to list relations for |
page | integer | No | 1 | Page number (1-indexed) |
perPage | integer | No | 20 | Items per page (1–100) |
includeMerged | string | No | false | Set to true to include merged relations for each root relation |
| Header | Required | Description |
|---|
Authorization | Yes | Bearer <token> — must be scoped to the requested project |
Response
{
"data": {
"items": [
{
"id": "rel-1",
"name": "Sony Music Publishing",
"email": "royalties@sonymusic.com",
"phone": "+1-212-833-8000",
"department": "Royalties",
"created_at": "2024-01-15T10:00:00Z",
"updated_at": "2024-06-01T12:00:00Z",
"merged": [
{ "id": "rel-2", "name": "Sony/ATV Music Publishing", "merged_at": "2024-03-01T09:00:00Z" }
]
}
],
"total_count": 15,
"page": 1,
"per_page": 20
}
}
The merged array only appears when includeMerged=true. Only root relations (non-merged) are returned in the list.
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/relations?projectId=a1b2c3d4-...&page=1&perPage=50" \
-H "Authorization: Bearer rp_your_token_here"
Get Relation
Returns a single relation by ID.
Request
GET /v1/relations/{relation_id}
Path Parameters
| Parameter | Type | Required | Description |
|---|
relation_id | string | Yes | The relation ID |
Query Parameters
| Parameter | Type | Required | Default | Description |
|---|
projectId | UUID | Yes | — | The project the relation belongs to |
includeMerged | string | No | false | Set to true to include merged relations |
| Header | Required | Description |
|---|
Authorization | Yes | Bearer <token> — must be scoped to the requested project |
Response
{
"data": {
"id": "rel-1",
"name": "Sony Music Publishing",
"email": "royalties@sonymusic.com",
"phone": "+1-212-833-8000",
"department": "Royalties",
"created_at": "2024-01-15T10:00:00Z",
"updated_at": "2024-06-01T12:00:00Z",
"merged": [
{ "id": "rel-2", "name": "Sony/ATV Music Publishing", "merged_at": "2024-03-01T09:00:00Z" }
]
}
}
Errors
| Status | Description |
|---|
400 | Missing projectId |
403 | Token is not scoped to the requested project |
404 | Relation not found |
Example
curl "https://api.royaltyport.com/v1/relations/rel-1?projectId=a1b2c3d4-..." \
-H "Authorization: Bearer rp_your_token_here"
