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

# Update Account

> Updates an existing account's properties.

Modify account details such as name, description, classification, or metadata.
Note that some properties like account status and purpose cannot be changed
through this endpoint. Changing classification from SECONDARY to PRIMARY will
fail if a PRIMARY account already exists.



## OpenAPI

````yaml PATCH /v1/accounts/{account_id}
openapi: 3.1.0
info:
  title: Payment Platform API
  version: 0.0.0
servers: []
security: []
tags:
  - name: Accounts
  - name: Payouts
  - name: Payments
paths:
  /v1/accounts/{account_id}:
    patch:
      tags:
        - Accounts
      summary: Update Account
      description: >-
        Updates an existing account's properties.


        Modify account details such as name, description, classification, or
        metadata.

        Note that some properties like account status and purpose cannot be
        changed

        through this endpoint. Changing classification from SECONDARY to PRIMARY
        will

        fail if a PRIMARY account already exists.
      operationId: Accounts_updateAccount
      parameters:
        - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAccountRequest'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '404':
          description: The server cannot find the requested resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationNotFoundProblemDetails'
        '409':
          description: The request conflicts with the current state of the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrimaryAccountExistsProblemDetails'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerProblemDetails'
components:
  parameters:
    AccountId:
      name: account_id
      in: path
      required: true
      description: The unique identifier of the account to update, starts with acct_
      schema:
        type: string
  schemas:
    UpdateAccountRequest:
      type: object
      properties:
        name:
          type: string
          description: New display name for the account
        description:
          type: string
          description: New description of the account's purpose
        classification:
          allOf:
            - $ref: '#/components/schemas/AccountClassification'
          description: New classification for the account
        metadata:
          type: object
          unevaluatedProperties:
            type: string
          description: Updated custom data associated with the account
      description: Input properties for updating an existing account
      examples:
        - name: Updated Business Account
          description: Updated description for business account
          metadata:
            department: operations
            costCenter: EMEA
    Account:
      type: object
      required:
        - accountId
        - name
        - purpose
        - classification
        - status
        - updatedAt
        - createdAt
      properties:
        accountId:
          type: string
          description: Unique identifier for the account
          readOnly: true
        name:
          type: string
          description: Display name for the account
        description:
          type: string
          description: Detailed description of the account's purpose
        purpose:
          allOf:
            - $ref: '#/components/schemas/AccountPurpose'
          description: The purpose of the account
        classification:
          allOf:
            - $ref: '#/components/schemas/AccountClassification'
          description: >-
            Classification that determines the account's priority and usage
            patterns
        status:
          allOf:
            - $ref: '#/components/schemas/AccountStatus'
          description: Current operational status of the account
          readOnly: true
        metadata:
          type: object
          unevaluatedProperties:
            type: string
          description: Additional custom data associated with the account
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the account was created
          readOnly: true
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the account was last updated
          readOnly: true
      description: |-
        Represents a financial account in the system
        Accounts are used to track balances and process transactions
      examples:
        - accountId: acc_12345
          name: Primary Business Account
          description: Main account for business operations
          purpose: OPERATING
          classification: PRIMARY
          status: ACTIVE
          metadata:
            department: finance
            costCenter: HQ
          updatedAt: '2025-04-29T13:29:15.064Z'
          createdAt: '2025-04-29T13:29:15.064Z'
    ValidationProblemDetails:
      type: object
      required:
        - status
        - title
        - code
        - type
        - detail
        - errors
      properties:
        status:
          type: number
          enum:
            - 400
          description: >-
            The HTTP status code as it appears in the response body.

            For this `ValidationProblemDetails` type, this field in the body
            will always be 400.
        title:
          type: string
          enum:
            - Validation Failed
          description: The problem title in the response body, fixed for this error type.
        code:
          type: string
          enum:
            - VALIDATION_ERROR
          description: >-
            The application-specific error code in the response body, fixed for
            this error type.
        type:
          type: string
          enum:
            - https://docs.bluerails.com/api/errors/validation-error
          description: The fixed type URI in the response body for validation errors.
        detail:
          type: string
          enum:
            - >-
              The request body is invalid. Please check the 'errors' field for
              more details.
          description: >-
            The default detail message in the response body for validation
            errors.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/FieldError'
          description: |-
            An array of objects detailing specific field validation errors.
            This field is required for a `ValidationProblemDetails` instance.
      allOf:
        - $ref: '#/components/schemas/ProblemDetails'
      examples:
        - type: https://docs.bluerails.com/api/errors/validation-error
          title: Validation Failed
          status: 400
          detail: >-
            The request body is invalid. Please check the 'errors' field for
            more details.
          instance: /v1/accounts
          code: VALIDATION_ERROR
          traceId: trace_c0177bce4d1547b3ad750eb54bbb9f4d
          errors:
            - field: classification
              message: >-
                Classification is required and must be either 'PRIMARY' or
                'SECONDARY'.
              code: MISSING_OR_INVALID_FIELD
              value: null
            - field: type
              message: Account type cannot be empty and must be a recognized type.
              value: ''
    OrganizationNotFoundProblemDetails:
      type: object
      required:
        - status
        - title
        - code
        - type
        - detail
      properties:
        status:
          type: number
          enum:
            - 404
          description: HTTP status code, always 404 for this error.
        title:
          type: string
          enum:
            - Organization Not Found
          description: Problem title, fixed for this error type.
        code:
          type: string
          enum:
            - ORGANIZATION_NOT_FOUND
          description: Application-specific error code.
        type:
          type: string
          enum:
            - https://docs.bluerails.com/api/errors/organization-not-found
          description: Type URI for this specific error.
        detail:
          type: string
          enum:
            - >-
              The specified organization could not be found or you do not have
              access.
          description: Default detail message.
      allOf:
        - $ref: '#/components/schemas/ProblemDetails'
      description: >-
        Problem details for when an organization cannot be found or is
        inaccessible.

        This corresponds to an HTTP 404 status.

        `code` in the body will be "ORGANIZATION_NOT_FOUND".
      examples:
        - type: https://docs.bluerails.com/api/errors/organization-not-found
          title: Organization Not Found
          status: 404
          detail: >-
            The specified organization could not be found or you do not have
            access.
          instance: /v1/accounts
          code: ORGANIZATION_NOT_FOUND
          traceId: trace_c0177bce4d1547b3ad750eb54bbb9f4d
    PrimaryAccountExistsProblemDetails:
      type: object
      required:
        - status
        - title
        - code
        - type
        - detail
      properties:
        status:
          type: number
          enum:
            - 409
          description: HTTP status code, always 409 for this error.
        title:
          type: string
          enum:
            - Primary Account Exists
          description: Problem title, fixed for this error type.
        code:
          type: string
          enum:
            - PRIMARY_ACCOUNT_EXISTS
          description: Application-specific error code.
        type:
          type: string
          enum:
            - https://docs.bluerails.com/api/errors/primary-account-exists
          description: Type URI for this specific error.
        detail:
          type: string
          enum:
            - >-
              A primary account already exists for this organization. Cannot
              create another one.
          description: Default detail message.
      allOf:
        - $ref: '#/components/schemas/ProblemDetails'
      description: |-
        Problem details for when an attempt is made to create a primary account
        but one already exists for the organization.
        This corresponds to an HTTP 409 status.
        `code` in the body will be "PRIMARY_ACCOUNT_EXISTS".
      examples:
        - type: https://docs.bluerails.com/api/errors/primary-account-exists
          title: Primary Account Exists
          status: 409
          detail: >-
            A primary account already exists for this organization. Cannot
            create another one.
          instance: /v1/accounts
          code: PRIMARY_ACCOUNT_EXISTS
          traceId: trace_c0177bce4d1547b3ad750eb54bbb9f4d
    InternalServerProblemDetails:
      type: object
      required:
        - status
        - title
        - code
        - type
        - detail
      properties:
        status:
          type: number
          enum:
            - 500
          description: HTTP status code, always 500 for this error.
        title:
          type: string
          enum:
            - Internal Server Error
          description: Problem title, fixed for this error type.
        code:
          type: string
          enum:
            - INTERNAL_SERVER_ERROR
          description: Application-specific error code.
        type:
          type: string
          enum:
            - https://docs.bluerails.com/api/errors/internal-server-error
          description: Type URI for this specific error.
        detail:
          type: string
          enum:
            - An unexpected error occurred while processing your request.
          description: Default detail message.
      allOf:
        - $ref: '#/components/schemas/ProblemDetails'
      description: |-
        Problem details for generic, unexpected internal server errors.
        This corresponds to an HTTP 500 status.
        `code` in the body will typically be "INTERNAL_SERVER_ERROR".
      examples:
        - type: https://docs.bluerails.com/api/errors/internal-server-error
          title: Internal Server Error
          status: 500
          detail: An unexpected error occurred while processing your request.
          instance: /v1/accounts
          code: INTERNAL_SERVER_ERROR
          traceId: trace_c0177bce4d1547b3ad750eb54bbb9f4d
    AccountClassification:
      type: string
      enum:
        - PRIMARY
        - SECONDARY
      description: |-
        Allowed classifications for an account
        Determines the account's priority and usage patterns
    AccountPurpose:
      type: string
      enum:
        - OPERATING
        - WALLET
        - REVENUE
        - TAX
        - RESERVE
        - OTHER
      description: >-
        Defines the primary purpose or category assigned by an SME to an
        account,

        facilitating the organization and management of funds within their
        treasury operations.

        From the perspective of Bluerails (the treasury solution provider), all
        these accounts

        represent liabilities.
    AccountStatus:
      type: string
      enum:
        - ACTIVE
        - INACTIVE
      description: |-
        The status of the account
        Indicates whether the account can be used for transactions
    FieldError:
      type: object
      required:
        - field
        - message
      properties:
        field:
          type: string
          description: The dot-separated path to the field in the request body.
        message:
          type: string
          description: Human-readable message describing the error for this field.
        code:
          type: string
          description: 'Optional: An application-specific code for this field error.'
        value:
          description: 'Optional: The actual value that caused the validation error.'
      description: |-
        Represents a specific field error, often part of a validation problem.
        Aligns with RFC 9457 extension for detailed field errors.
    ProblemDetails:
      type: object
      required:
        - type
        - title
        - status
        - detail
        - code
        - traceId
      properties:
        type:
          type: string
          format: uri
          description: >-
            A URI reference that identifies the problem type.

            When dereferenced, it should provide human-readable documentation
            for the problem type.
        title:
          type: string
          description: |-
            A short, human-readable summary of the problem type.
            It SHOULD NOT change from occurrence to occurrence of the problem.
        status:
          type: integer
          format: int32
          description: >-
            The HTTP status code generated by the origin server for this
            occurrence of the problem.

            This should match the HTTP status of the response.
        detail:
          type: string
          description: >-
            A human-readable explanation specific to this occurrence of the
            problem.
        instance:
          type: string
          format: uri
          description: >-
            A URI reference that identifies the specific occurrence of the
            problem.

            It may or may not yield further information if dereferenced.
        code:
          type: string
          description: |-
            An application-specific error code that can be used by the client
            to programmatically identify the error.
        traceId:
          type: string
          description: >-
            A unique identifier for the entire trace or request lifecycle,

            crucial for correlating logs across services and for effective
            support.

            This identifier should match the value in the `X-Trace-Id` response
            header.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/FieldError'
          description: |-
            An array of objects providing details about more specific errors,
            especially useful for validation errors (HTTP 400/422).
      description: >-
        Represents an API error response compliant with RFC 9457 "Problem
        Details for HTTP APIs".

        This is the standardized error structure for all API error responses.

````