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

# Relations

> List and retrieve relations (contacts) for a project.

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

```
GET /v1/relations
```

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

### Headers

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

### Response

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

<Note>
  The `merged` array only appears when `includeMerged=true`. Only root relations (non-merged) are returned in the list.
</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/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 |

### Headers

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

### Response

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

```bash theme={null}
curl "https://api.royaltyport.com/v1/relations/rel-1?projectId=a1b2c3d4-..." \
  -H "Authorization: Bearer rp_your_token_here"
```