---
title: "Update a firm by ID"
url: "https://developer-staging.agentsync.io/apis/identity/versions/1ed33a2c-924a-434c-9643-fbc531dea1b8/operations/updateFirmV2"
---

> Full API specification: https://developer-staging.agentsync.io/apis/identity/versions/1ed33a2c-924a-434c-9643-fbc531dea1b8.md

# Update a firm by ID

`PUT` `/v2/firms/{firmId}`

Operation ID: `updateFirmV2`

Updates mutable fields on a firm visible to the authenticated customer. The fields `npn` and `fein` are immutable and cannot be changed via this endpoint. Omitted fields leave the stored value unchanged (partial update). Returns 404 if the firm does not exist or is not visible to the authenticated customer. A 403 is returned only when the caller's token lacks the required scope; cross-customer access returns 404, not 403.

## Path parameters

- `firmId` (string, uuid, required) - ID of the firm

## Request body (required)

Content types: `application/json`

## Responses

- `200` - Firm updated successfully.
- `400` - One or more request fields failed validation
- `401` - No valid bearer token was presented
- `403` - The token does not carry the required scope
- `404` - The requested resource does not exist or is not visible to the caller
- `429` - Rate limit exceeded. The caller has exceeded the maximum number of requests allowed per rate-limit window for the authenticated credential. NOTE: The response body for this status deviates from the standard V2 error shape ({message, details, code}). The body contains only a top-level "message" string. Clients should treat the Retry-After header as the authoritative retry signal and must not parse the message string.
- `500` - An unexpected server error occurred

## OpenAPI definition

```yaml
openapi: 3.0.1
info:
  title: Identity API
  version: v1.275.8
servers:
  - url: https://api.sandbox.agentsync.io/id
    description: Sandbox server
  - url: https://api.agentsync.io/id
    description: Production server
paths:
  /v2/firms/{firmId}:
    put:
      summary: Update a firm by ID
      description: >
        Updates mutable fields on a firm visible to the authenticated customer.
        The fields `npn` and `fein` are immutable and cannot be changed via this
        endpoint. Omitted fields leave the stored value unchanged (partial
        update).


        Returns 404 if the firm does not exist or is not visible to the
        authenticated customer. A 403 is returned only when the caller's token
        lacks the required scope; cross-customer access returns 404, not 403.
      operationId: updateFirmV2
      tags:
        - Firms
      security:
        - oauth2:
            - identity.profiles.write
      parameters:
        - $ref: "#/components/parameters/FirmIdParam"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateFirmRequest"
      responses:
        "200":
          description: Firm updated successfully.
          headers:
            ratelimit-limit:
              $ref: "#/components/headers/ratelimit-limit"
            ratelimit-remaining:
              $ref: "#/components/headers/ratelimit-remaining"
            ratelimit-reset:
              $ref: "#/components/headers/ratelimit-reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FirmV2"
        "400":
          $ref: "#/components/responses/V2BadRequest"
        "401":
          $ref: "#/components/responses/V2Unauthorized"
        "403":
          $ref: "#/components/responses/V2Forbidden"
        "404":
          $ref: "#/components/responses/V2NotFound"
        "429":
          $ref: "#/components/responses/V2TooManyRequests"
        "500":
          $ref: "#/components/responses/V2InternalServerError"
security:
  - oauth2:
      - identity.profiles.write
components:
  parameters:
    FirmIdParam:
      name: firmId
      in: path
      description: ID of the firm
      required: true
      schema:
        type: string
        format: uuid
  schemas:
    UpdateFirmRequest:
      title: UpdateFirmRequest
      description: >
        Fields that may be updated on a firm. All fields are optional — omitted
        fields leave the stored value unchanged. The `npn` and `fein` fields are
        immutable and cannot be set via this endpoint.
      type: object
      properties:
        name:
          type: string
          description: Legal name of the firm.
          example: Acme Insurance LLC
        email:
          type: string
          format: email
          description: Primary contact email address.
          example: contact@acme.com
        type:
          type: string
          description: Business entity type (SC, LLC, SP).
          example: LLC
        finraCrdNumber:
          type: string
          description: FINRA CRD number (digits only, max 11 characters).
          pattern: ^[0-9]*$
          maxLength: 11
          example: "12345"
    FirmV2:
      title: FirmV2
      description: >
        Customer-facing firm resource. The FEIN is always masked to ****<last4>;
        the full FEIN is available only via GET /v2/firms/{firmId}/fein
        (audited).
      type: object
      required:
        - id
        - npn
        - createdAt
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the firm.
          readOnly: true
          example: 550e8400-e29b-41d4-a716-446655440000
        npn:
          type: string
          description: National Producer Number.
          readOnly: true
          example: "1234567"
        name:
          type: string
          description: Legal name of the firm.
          example: Acme Insurance LLC
        email:
          type: string
          format: email
          description: Primary contact email address.
          example: contact@acme.com
        type:
          type: string
          description: Business entity type (SC, LLC, SP).
          example: LLC
        finraCrdNumber:
          type: string
          description: FINRA CRD number (digits only, max 11 characters).
          example: "12345"
        fein:
          type: string
          description: >
            Masked Federal Employer Identification Number. Always returned as
            ****<last4>. The full FEIN is never exposed by this endpoint.
          readOnly: true
          example: "****6789"
        testAccount:
          type: boolean
          description: Whether this is a test account.
          example: false
        createdAt:
          type: string
          format: date-time
          description: ISO-8601 UTC timestamp when the firm was created.
          readOnly: true
          example: 2024-01-15T10:30:00Z
        updatedAt:
          type: string
          format: date-time
          description: ISO-8601 UTC timestamp of the last update.
          readOnly: true
          example: 2024-06-01T14:22:00Z
    V2Error:
      type: object
      required:
        - message
        - details
        - code
      properties:
        message:
          type: string
          description: Human-readable error summary. Do not parse — use "code" for
            branching.
          example: Validation failed
        details:
          type: array
          description: Per-field validation errors. Empty for all non-400 responses.
          items:
            $ref: "#/components/schemas/V2FieldError"
        code:
          type: string
          description: Stable machine-readable error code.
          enum:
            - validation_failed
            - unauthorized
            - unauthorized_scope
            - resource_not_found
            - conflict
            - unprocessable
            - unsupported_media_type
            - rate_limited
            - internal
          example: validation_failed
    V2FieldError:
      type: object
      required:
        - param
        - message
      properties:
        param:
          type: string
          description: The request field that failed validation
          example: email
        message:
          type: string
          description: Human-readable description of the failure
          example: must not be blank
  headers:
    ratelimit-limit:
      description: >
        Maximum number of requests allowed per rate-limit window for the
        authenticated credential. The value returned in this header is
        authoritative; do not cache it.
      schema:
        type: integer
    ratelimit-remaining:
      description: Number of requests remaining in the current rate-limit window.
      schema:
        type: integer
    ratelimit-reset:
      description: >
        Unix timestamp (seconds) after which at least one additional request
        slot becomes available. In a sliding window this is a hint, not a hard
        reset point — retrying exactly at this instant may still return 429
        under sustained load.
      schema:
        type: integer
    Retry-After:
      description: >
        Minimum seconds to wait before retrying. Use this value directly as your
        retry delay; it already accounts for any server-side backoff.
      schema:
        type: integer
  responses:
    V2BadRequest:
      description: One or more request fields failed validation
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/V2Error"
          example:
            message: Validation failed
            code: validation_failed
            details:
              - param: email
                message: must not be blank
    V2Unauthorized:
      description: No valid bearer token was presented
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/V2Error"
          example:
            message: Authentication required
            code: unauthorized
            details: []
    V2Forbidden:
      description: The token does not carry the required scope
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/V2Error"
          example:
            message: Insufficient scope
            code: unauthorized_scope
            details: []
    V2NotFound:
      description: The requested resource does not exist or is not visible to the caller
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/V2Error"
          example:
            message: Resource not found
            code: resource_not_found
            details: []
    V2TooManyRequests:
      description: >
        Rate limit exceeded. The caller has exceeded the maximum number of
        requests allowed per rate-limit window for the authenticated credential.

        NOTE: The response body for this status deviates from the standard V2
        error shape ({message, details, code}). The body contains only a
        top-level "message" string. Clients should treat the Retry-After header
        as the authoritative retry signal and must not parse the message string.
      headers:
        ratelimit-limit:
          $ref: "#/components/headers/ratelimit-limit"
        ratelimit-remaining:
          $ref: "#/components/headers/ratelimit-remaining"
        ratelimit-reset:
          $ref: "#/components/headers/ratelimit-reset"
        Retry-After:
          $ref: "#/components/headers/Retry-After"
      content:
        application/json:
          schema:
            type: object
            required:
              - message
            properties:
              message:
                type: string
          example:
            message: API rate limit exceeded
    V2InternalServerError:
      description: An unexpected server error occurred
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/V2Error"
          example:
            message: An unexpected error occurred
            code: internal
            details: []
  securitySchemes:
    oauth2:
      type: oauth2
      description: >
        OAuth2 client credentials. The `tokenUrl` below is the SANDBOX token
        endpoint; for production use `https://auth.agentsync.io/oauth2/token`.
        OpenAPI 3.0 permits only one token URL per flow, so both cannot be
        expressed here — see the Authentication section for the full environment
        table.
      flows:
        clientCredentials:
          tokenUrl: https://auth.sandbox.agentsync.io/oauth2/token
          scopes:
            identity.profiles.read: Read access to producer profile resources (V2 customer-facing)
            identity.profiles.write: Write access to producer profile resources (V2 customer-facing)
```