---
title: "Assign or update a firm role on an entity"
method: POST
path: "/entities/update_firm_role"
deprecated: true
---

# Assign or update a firm role on an entity

`POST /entities/update_firm_role`

> **Deprecated.**

⚠️ **DEPRECATED**: This endpoint is deprecated and will be removed in a future version. Please use the new endpoints` /entities/{entity_id}/firm_role_assignments` instead.

Assigns a firm role to a firm user for the given entity. You may identify the entity by `entity_id` or `external_entity_id`, and the firm user by `firm_user_id` or `firm_user_email`. If `replace_existing_firm_role` is true, existing assignments for that user+firm on the entity are removed before adding the new one.

## Request body

- UpdateFirmRoleRequest
  - `entity_id` integer
  - `external_entity_id` string
  - `firm_role_name` string, required
  - `firm_user_id` integer, nullable
  - `firm_user_email` string, email, nullable
  - `replace_existing_firm_role` boolean

## Response `200`

Updated entity with role assignment applied

- Entity
  - `id` integer, required
  - `entity_type` string, required
  - `name` string, required
  - `street` string, nullable
  - `state` string, nullable
  - `city` string, nullable
  - `zip` string, nullable
  - `country` string, nullable
  - `tax_return_name` string, required
  - `created_at` string, date-time, required
  - `upload_link` string, uri, required
  - `user` Client, required
    - `id` integer, required
    - `email` string, email, required
    - `fname` string, required
    - `lname` string, required
    - `full_name` string, nullable
    - `time_zone` string, nullable
    - `phone_number` string, nullable
    - `preferred_name` string, nullable
    - `created_at` string, date-time, required
    - `active` boolean, required — Derived from User#paying
    - `assigned_advisor_id` integer, required
    - `work_phone_number` string, nullable
    - `work_phone_extension` string, nullable
    - `work_email` string, email, nullable
    - `external_user_id` string, nullable
    - `assigned_advisor` string, nullable — Assigned advisor full name (string), not an object
  - `business_email` string, nullable
  - `other_email` string, nullable
  - `owners` Client[], required — Owners resolved from owner_ids; serialized as clients
    - `id` integer, required
    - `email` string, email, required
    - `fname` string, required
    - `lname` string, required
    - `full_name` string, nullable
    - `time_zone` string, nullable
    - `phone_number` string, nullable
    - `preferred_name` string, nullable
    - `created_at` string, date-time, required
    - `active` boolean, required — Derived from User#paying
    - `assigned_advisor_id` integer, required
    - `work_phone_number` string, nullable
    - `work_phone_extension` string, nullable
    - `work_email` string, email, nullable
    - `external_user_id` string, nullable
    - `assigned_advisor` string, nullable — Assigned advisor full name (string), not an object
  - `external_entity_id` string, nullable
  - `deleted_at` string, date-time, nullable
  - `hash_id` string, required

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not found

---

[API](https://skmtc.net/soraban/apis/soraban-private-api.md) · [All operations](https://skmtc.net/soraban/apis/soraban-private-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/soraban/soraban-private-api/versions/0dfdfa10c993/schema)