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

# Collaboration Guide

> Inviting other users to view and collaborate on estate cases.

# Collaboration

Case owners can invite other users to collaborate on an estate case. Collaborators can be family members, co-executors, attorneys, financial advisors, or anyone who needs access.

## Inviting a Collaborator

```bash theme={null}
curl -X POST "https://api.example.com/v1/cases/{case_id}/collaborators" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Johnson",
    "role": "editor",
    "permissions": {
      "can_manage_documents": true,
      "can_manage_financials": true,
      "can_manage_probate": false,
      "can_manage_collaborators": false,
      "can_use_tools": true
    },
    "message": "Hi John, I am sharing access to Grandpa Vernen estate case with you."
  }'
```

An invitation email is sent to the collaborator. They can accept or decline.

## Roles & Permissions

### Roles

| Role     | Access                                               |
| -------- | ---------------------------------------------------- |
| `owner`  | Full control. Only one owner per case (the creator). |
| `editor` | Can read and write data based on their permissions.  |
| `viewer` | Read-only access to all case data.                   |

### Granular Permissions

Editors can have fine-grained permissions beyond their role:

| Permission                 | Description                                              |
| -------------------------- | -------------------------------------------------------- |
| `can_manage_collaborators` | Invite, update, or remove other collaborators            |
| `can_manage_documents`     | Upload, update, and delete documents                     |
| `can_manage_financials`    | Modify financial accounts, bank accounts, transactions   |
| `can_manage_probate`       | Manage probate filings, deadlines, claims, distributions |
| `can_use_tools`            | Use phone, email, fax, and notarization tools            |

Viewers always have read-only access regardless of permission settings.

## Invitation Flow

```
Owner sends invite  ->  Status: pending
                        (email sent to collaborator)

Collaborator accepts ->  Status: accepted
                         (case appears in their dashboard)

Collaborator declines -> Status: declined

Owner revokes access ->  Status: revoked
                         (DELETE endpoint)
```

## Managing Collaborators

### List all collaborators

````bash theme={null}
curl "https://api.example.com/v1/cases/{case_id}/collaborators"```

### Update a collaborator's role or permissions

```bash
curl -X PATCH ".../collaborators/{collaborator_id}" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "viewer",
    "permissions": {
      "can_use_tools": false
    }
  }'
````

### Resend a pending invitation

````bash theme={null}
curl -X POST ".../collaborators/{collaborator_id}/resend"```

### Remove a collaborator

```bash
curl -X DELETE ".../collaborators/{collaborator_id}"```

## How Collaborators See Shared Cases

When a collaborator accepts an invite, the case appears in their `/users/me/cases` listing with their assigned role:

```json
{
  "data": [
    {
      "id": "01K5WF06MJ6T99HRYE78AN7XM8",
      "deceased_name": "John Jonas Johnson",
      "role": "editor",
      "estate_value": "unknown",
      "flow_position": "Closure - Decisions - Initial"
    }
  ]
}
````