# Share a dynamic set with other users.

`POST /sets/{set_id}/share`

> Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-share-set · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmShareSet` · Tag: Dynamic Sets

Grants specified access levels to other users for this dynamic set. Only the set's owner or a manager-level collaborator may share the set. Access levels are: **R** (viewer, read-only), **E** (restricted editor), **F** (editor, can modify set and associated listings), **M** (manager, can share and upgrade the set), and **N** (disabled, revokes access). Sharing with a user who already has access updates their level to the newly specified one. Returns the updated dynamic set. **Works for free and paid sets.**

## Request

`POST https://api.usewheelhouse.com/ss_api/v1/sets/{set_id}/share`

Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `set_id` | integer | yes | The Wheelhouse internal dynamic set ID. |

### Request body (`application/json`, required)

- `access` (object, required): Access levels to grant, keyed by level code.
  - `R` (array of integer): Array of user IDs to grant viewer (read-only) access.
  - `E` (array of integer): Array of user IDs to grant restricted editor access.
  - `F` (array of integer): Array of user IDs to grant editor access.
  - `M` (array of integer): Array of user IDs to grant manager access.
  - `N` (array of integer): Array of user IDs to disable (revoke access).

### Example request

```bash
curl -X POST 'https://api.usewheelhouse.com/ss_api/v1/sets/{set_id}/share' \
  -H 'X-Integration-Api-Key: <your RM API key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "access": {}
}'
```

Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say.

## Responses

### 200

The dynamic set with updated sharing settings.

Body (`application/json`): object `dynamic_set_response`

A dynamic set (comp set).

- `id` (integer, required): The Wheelhouse internal dynamic set ID.
- `user_id` (integer, required): The Wheelhouse internal ID of the user that owns the set.
- `name` (string, required): The set name.
- `description` (string, nullable): An optional description of the set.
- `kind` (string, one of: `competitive`, `market`, `neighborhood`, `marketing`, `acquisition`, `underwriting`, `other`, `merchandising`): The intended use case for the set:
  - `competitive` — tracks direct competitor properties.
  - `market` — broad market-wide overview.
  - `neighborhood` — properties in the same geographic sub-area.
  - `marketing` — properties used as marketing or positioning references.
  - `acquisition` — evaluating potential acquisition targets.
  - `underwriting` — used in underwriting or investment analysis.
  - `merchandising` — set curated for merchandising purposes.
  - `other` — general-purpose or uncategorized set.
- `currency` (string, nullable): The ISO-4217 3-letter currency code of the set.
- `is_static` (boolean): Whether the set membership is static. Non-static sets are kept in sync automatically based on the set's boundary and filters.
- `is_paid` (boolean): Whether the set is on the paid Dynamic Sets plan. Only paid sets expose the set-level analytics endpoints (aggregated_metrics, time_series, distribution, changelog), which return `404 Not Found` for a free set. Endpoints for building and reviewing a set — including its member listings and associated_listings — work on free sets too. See the Dynamic Sets section for the full per-endpoint breakdown. Upgrade a free set via `POST /sets/{set_id}/upgrade`.
- `filters` (object, nullable): The filter criteria used to select member listings (non-static sets). Keys are listing attributes/metrics, values contain `lower`/`upper` bounds or `one_of` lists.
- `boundary` (array of array of array of array of number, nullable, each item each item each item min items: 2, max items: 2): The geographic boundary of the set as MultiPolygon coordinates (`[[[[lng, lat], ...]]]`), if one is defined.

  The four levels of nesting are: **polygons** → **rings** → **points** → **coordinates**.

  - **Polygons** (`boundary[i]`): Each element is one polygon.
  - **Rings** (`boundary[i][j]`): Each polygon contains one or more linear rings. The first ring is the exterior boundary (outer shell of the shape); any subsequent rings represent interior boundaries (holes inside the polygon).
  - **Points** (`boundary[i][j][k]`): Each ring is an array of `[longitude, latitude]` coordinate pairs.
  - **Coordinates** (`boundary[i][j][k][0/1]`): Each point is `[longitude, latitude]` as floating-point numbers.
- `listing_counts` (object): Number of member listings in the set per status.
  - `active` (integer)
  - `hidden` (integer)
  - `review` (integer)
  - `removed` (integer)
- `updated_at` (string (date-time)): When the set was last updated (ISO-8601).

Example shape (generated from the schema; placeholder values, not a real response):

```json
{
  "id": 0,
  "user_id": 0,
  "name": "string",
  "description": "string",
  "kind": "competitive",
  "currency": "string",
  "is_static": true,
  "is_paid": true,
  "filters": {},
  "boundary": [
    [
      [
        [
          0,
          0
        ]
      ]
    ]
  ],
  "listing_counts": {
    "active": 0,
    "hidden": 0,
    "review": 0,
    "removed": 0
  },
  "updated_at": "2026-01-01T00:00:00Z"
}
```

### 400

Invalid access levels or user IDs.

### 401

API key authorization failed.

### 403

The API key is read-only, or the user is not the set's owner or a manager.

### 404

Dynamic set not found or not accessible to the user.

### 429

Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy.

Body (`application/json`): object

- `error` (string, example: `API token is at rate limit`)

Example shape (generated from the schema; placeholder values, not a real response):

```json
{
  "error": "API token is at rate limit"
}
```
