Entities

List and retrieve entities (companies, labels, publishers) for a project.

List Entities

Returns a paginated list of root entities for a project. Entities represent companies, labels, publishers, and other organizations referenced in contracts.

Request

GET /v1/entities

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
roles	string	No	—	Comma-separated list of contract roles to filter by. Supported values: assignee, assignor. Returns only entities that appear in at least one contract under any of the given roles.

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.

When roles is omitted (or empty), all entities are returned. When multiple roles are passed (e.g. roles=assignee,assignor), entities matching any of the roles are returned.

Headers

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

Response

{
  "data": [
    {
      "id": "entity-1",
      "internal_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Sony Music Entertainment",
      "email": "[e-mail]",
      "phone": "[phone]",
      "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
internal_uuid	string	Stable UUID for the entity. Useful for joining against external systems that key on UUIDs, and can also be used in place of id when calling GET /v1/entities/{entity_id}.
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"

Filter to entities that appear as an assignee or assignor on at least one contract:

curl "https://api.royaltyport.com/v1/entities?projectId=a1b2c3d4-...&roles=assignee,assignor" \
  -H "Authorization: Bearer rp_your_token_here"

---

Get Entity

Returns a single entity by its numeric id or its internal_uuid.

Request

GET /v1/entities/{entity_id}

Path Parameters

Parameter	Type	Required	Description
entity_id	string	Yes	The entity’s numeric id or its internal_uuid

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

Headers

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

Response

{
  "data": {
    "id": "entity-1",
    "internal_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name": "Sony Music Entertainment",
    "email": "[e-mail]",
    "phone": "[phone]",
    "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"

Fetch by internal_uuid instead of the numeric id:

curl "https://api.royaltyport.com/v1/entities/f47ac10b-58cc-4372-a567-0e02b2c3d479?projectId=a1b2c3d4-..." \
  -H "Authorization: Bearer rp_your_token_here"