List Entities
Returns a paginated list of root entities for a project. Entities represent companies, labels, publishers, and other organizations referenced in contracts.
Request
Query Parameters
| Parameter | Type | Required | Default | Description |
|---|
projectId | UUID | Yes | — | The project to list entities 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 entities for each root entity |
Royaltyport de-duplicates entities by merging variants into a single root record. Use includeMerged=true to see which entity records have been merged under each root.
| Header | Required | Description |
|---|
Authorization | Yes | Bearer <token> — must be scoped to the requested project |
Response
{
"data": [
{
"id": "entity-1",
"name": "Sony Music Entertainment",
"email": "legal@sonymusic.com",
"phone": "+1-212-833-8000",
"address": "25 Madison Ave, New York, NY 10010",
"shorthand": "SME",
"division_of": "entity-5",
"project_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"merged": [
{ "id": "entity-2", "name": "Sony Music" },
{ "id": "entity-3", "name": "SME" }
]
}
]
}
The merged array only appears when includeMerged=true. Without it, only the base entity fields are returned.
Response Fields
| Field | Type | Description |
|---|
id | string | Unique entity identifier |
name | string | Entity name |
email | string | Contact email address, if available |
phone | string | Contact phone number, if available |
address | string | Mailing or registered address, if available |
shorthand | string | Abbreviated name or alias used for the entity, if available |
division_of | string | ID of the parent entity if this entity is a division or subsidiary, if applicable |
project_id | string | The project this entity belongs to |
created_at | string | ISO 8601 timestamp of when the entity was created |
updated_at | string | ISO 8601 timestamp of when the entity was last updated |
merged | array | Merged entity records (only present when includeMerged=true) |
Fields such as email, phone, address, shorthand, and division_of are only included in the response when they have a value — null fields are omitted.
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/entities?projectId=a1b2c3d4-...&includeMerged=true" \
-H "Authorization: Bearer rp_your_token_here"
Get Entity
Returns a single entity by ID.
Request
GET /v1/entities/{entity_id}
Path Parameters
| Parameter | Type | Required | Description |
|---|
entity_id | string | Yes | The entity ID |
Query Parameters
| Parameter | Type | Required | Default | Description |
|---|
projectId | UUID | Yes | — | The project the entity belongs to |
includeMerged | string | No | false | Set to true to include merged entities |
| Header | Required | Description |
|---|
Authorization | Yes | Bearer <token> — must be scoped to the requested project |
Response
{
"data": {
"id": "entity-1",
"name": "Sony Music Entertainment",
"email": "legal@sonymusic.com",
"phone": "+1-212-833-8000",
"address": "25 Madison Ave, New York, NY 10010",
"shorthand": "SME",
"division_of": "entity-5",
"project_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"merged": [
{ "id": "entity-2", "name": "Sony Music" }
]
}
}
Errors
| Status | Description |
|---|
400 | Missing projectId |
403 | Token is not scoped to the requested project |
404 | Entity not found |
Example
curl "https://api.royaltyport.com/v1/entities/entity-1?projectId=a1b2c3d4-...&includeMerged=true" \
-H "Authorization: Bearer rp_your_token_here"
