> ## Documentation Index
> Fetch the complete documentation index at: https://docs.royaltyport.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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. |

<Tip>
  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.
</Tip>

<Note>
  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.
</Note>

### Headers

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

### Response

```json theme={null}
{
  "data": [
    {
      "id": "entity-1",
      "internal_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "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" }
      ]
    }
  ]
}
```

<Note>
  The `merged` array only appears when `includeMerged=true`. Without it, only the base entity fields are returned.
</Note>

### 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`)                                                                                                                |

<Note>
  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.
</Note>

### Errors

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

### Example

```bash theme={null}
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:

```bash theme={null}
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

```json theme={null}
{
  "data": {
    "id": "entity-1",
    "internal_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "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

```bash theme={null}
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`:

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