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

# Update metadata

> Update existing metadata for a given entity.

**Update metadata** modifies specific properties using [JSON Patch](http://jsonpatch.com/) operations. Unlike [Set metadata](./set-metadata), this enables partial updates without replacing the entire object.

Supported operations: **add**, **replace**, **remove**, **move**, **copy**, and **test**.

The response includes an `ETag` header for the new version. Use `If-Match` to prevent conflicting concurrent modifications.

<Note>
  Operations are applied sequentially and validated to ensure metadata remains valid.
</Note>


## OpenAPI

````yaml _media/specs/core-openapi.mintlify.json patch /core/{entity}/{entityId}/metadata
openapi: 3.1.0
info:
  version: 0.1.0
  title: Core API
  description: >-
    The Core API provides essential building blocks that empower businesses to
    embed financial services into their applications.
  contact:
    name: Uphold API Team
    email: developers@uphold.com
    url: https://developer.uphold.com
servers:
  - url: https://api.enterprise.sandbox.uphold.com
    description: Sandbox
  - url: https://api.enterprise.uphold.com
    description: Production
security:
  - OAuth2: []
tags:
  - name: Authentication
    description: Authentication.
  - name: Countries
    description: Countries.
  - name: Users
    description: Users.
  - name: KYC
    description: Individual User's KYC.
  - name: KYB
    description: Business User's KYB.
  - name: Capabilities
    description: User capabilities.
  - name: Terms of service
    description: User terms of service.
  - name: Files
    description: Files.
  - name: Assets
    description: Assets, networks and rails.
  - name: Accounts
    description: Accounts.
  - name: External accounts
    description: External accounts.
  - name: Transactions
    description: Transactions.
  - name: Portfolio
    description: Portfolio.
  - name: Statements
    description: Statements.
  - name: Metadata
    description: Metadata.
  - name: Webhooks
    description: Webhooks.
paths:
  /core/{entity}/{entityId}/metadata:
    patch:
      tags:
        - Metadata
      summary: Update metadata
      description: Update existing metadata for a given entity.
      operationId: core.update-metadata
      parameters:
        - $ref: '#/components/parameters/metadata-entity'
        - $ref: '#/components/parameters/metadata-entity-id'
        - $ref: '#/components/parameters/metadata-if-match'
      requestBody:
        $ref: '#/components/requestBodies/update-metadata-request-body'
      responses:
        '200':
          $ref: '#/components/responses/update-metadata-response'
        '404':
          $ref: '#/components/responses/metadata-not-found'
        '412':
          $ref: '#/components/responses/metadata-precondition-failed'
        '413':
          $ref: '#/components/responses/metadata-payload-too-large'
        '422':
          $ref: '#/components/responses/update-metadata-unprocessable-entity-response'
components:
  parameters:
    metadata-entity:
      name: entity
      description: The type of entity whose metadata is being accessed.
      in: path
      required: true
      schema:
        type: string
        enum:
          - accounts
          - external-accounts
          - files
          - transactions
          - users
      examples:
        User Entity:
          value: users
    metadata-entity-id:
      name: entityId
      description: The unique identifier of the entity whose metadata is being accessed.
      in: path
      required: true
      schema:
        type: string
      examples:
        User ID:
          value: me
    metadata-if-match:
      name: If-Match
      description: Ensures conditional update by matching the current metadata revision.
      in: header
      style: simple
      explode: false
      schema:
        type: string
        pattern: ^(?:W\/)?"([A-Fa-f0-9]{64})"$
      examples:
        Metadata Revision:
          value: '"abc123def456789012345678901234567890123456789012345678901234abcd"'
  requestBodies:
    update-metadata-request-body:
      content:
        application/json-patch+json:
          schema:
            $ref: '#/components/schemas/json-patch-operations'
          examples:
            Add Property:
              value:
                - op: add
                  path: /status
                  value: active
            Update Property:
              value:
                - op: replace
                  path: /tier
                  value: gold
            Remove Property:
              value:
                - op: remove
                  path: /region
  responses:
    update-metadata-response:
      description: Metadata updated.
      headers:
        ETag:
          $ref: '#/components/headers/metadata-etag'
        x-uphold-request-id:
          description: >-
            A unique identifier for the request that can be shared with Uphold
            for troubleshooting purposes.
          required: true
          schema:
            type: string
            format: uuid
          examples:
            Request ID:
              value: 9092ee4d-f0fb-42e9-8787-b668dbcec531
      content:
        application/json:
          schema:
            type: object
            properties:
              metadata:
                $ref: '#/components/schemas/metadata'
            required:
              - metadata
          examples:
            Metadata Patched:
              value:
                metadata:
                  externalId: 123
    metadata-not-found:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            Metadata Not Found:
              value:
                code: entity_not_found
                message: The entity metadata cannot be found
                details:
                  entity: metadata
            Entity Not Found:
              value:
                code: entity_not_found
                message: The <entity> cannot be found
                details:
                  entity: <entity>
      headers:
        x-uphold-request-id:
          description: >-
            A unique identifier for the request that can be shared with Uphold
            for troubleshooting purposes.
          required: true
          schema:
            type: string
            format: uuid
          examples:
            Request ID:
              value: 9092ee4d-f0fb-42e9-8787-b668dbcec531
    metadata-precondition-failed:
      description: Precondition failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            Metadata Precondition Failed:
              value:
                code: precondition_failed
                message: The If-Match header value does not match the current metadata
      headers:
        x-uphold-request-id:
          description: >-
            A unique identifier for the request that can be shared with Uphold
            for troubleshooting purposes.
          required: true
          schema:
            type: string
            format: uuid
          examples:
            Request ID:
              value: 9092ee4d-f0fb-42e9-8787-b668dbcec531
    metadata-payload-too-large:
      description: Payload too large.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            Metadata Payload Too Large:
              value:
                code: content_too_large
                message: The entity metadata size is greater than maximum size limit
                details:
                  threshold:
                    unit: characters
                    limit: 1024
      headers:
        x-uphold-request-id:
          description: >-
            A unique identifier for the request that can be shared with Uphold
            for troubleshooting purposes.
          required: true
          schema:
            type: string
            format: uuid
          examples:
            Request ID:
              value: 9092ee4d-f0fb-42e9-8787-b668dbcec531
    update-metadata-unprocessable-entity-response:
      description: Unprocessable entity.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            Replace Operation Path Not Found:
              value:
                code: json_patch_failed
                message: The entity metadata patch operation failed to apply
                details:
                  operation:
                    index: 0
                    op: replace
                    path: /items/10
                  reason: >-
                    replace operation does not apply: doc is missing path:
                    /items/10: missing value
            Remove Operation Path Not Found:
              value:
                code: json_patch_failed
                message: The entity metadata patch operation failed to apply
                details:
                  operation:
                    index: 0
                    op: remove
                    path: /region
                  reason: >-
                    remove operation does not apply: doc is missing path:
                    /region: missing value
      headers:
        x-uphold-request-id:
          description: >-
            A unique identifier for the request that can be shared with Uphold
            for troubleshooting purposes.
          required: true
          schema:
            type: string
            format: uuid
          examples:
            Request ID:
              value: 9092ee4d-f0fb-42e9-8787-b668dbcec531
  schemas:
    json-patch-operations:
      description: An array of RFC 6902 JSON Patch operations.
      type: array
      minItems: 1
      items:
        type: object
        discriminator:
          propertyName: op
          mapping:
            add:
              $ref: '#/components/schemas/json-patch-with-value'
            copy:
              $ref: '#/components/schemas/json-patch-with-from'
            move:
              $ref: '#/components/schemas/json-patch-with-from'
            remove:
              $ref: '#/components/schemas/json-patch-remove'
            replace:
              $ref: '#/components/schemas/json-patch-with-value'
            test:
              $ref: '#/components/schemas/json-patch-with-value'
        oneOf:
          - $ref: '#/components/schemas/json-patch-with-value'
            title: Add/Replace/Test
          - $ref: '#/components/schemas/json-patch-with-from'
            title: Move/Copy
          - $ref: '#/components/schemas/json-patch-remove'
            title: Remove
        required:
          - op
    metadata:
      type: object
      additionalProperties: true
      minProperties: 1
    error:
      description: The error information.
      allOf:
        - $ref: '#/components/schemas/feedback'
    json-patch-with-value:
      type: object
      additionalProperties: false
      properties:
        op:
          type: string
          enum:
            - add
            - replace
            - test
        path:
          type: string
        value:
          oneOf:
            - type: string
            - type: number
            - type: boolean
            - type: object
            - type: array
            - type: 'null'
      required:
        - op
        - path
        - value
    json-patch-with-from:
      type: object
      additionalProperties: false
      properties:
        op:
          type: string
          enum:
            - move
            - copy
        path:
          type: string
        from:
          type: string
      required:
        - op
        - path
        - from
    json-patch-remove:
      type: object
      additionalProperties: false
      properties:
        op:
          type: string
          const: remove
        path:
          type: string
      required:
        - op
        - path
    feedback:
      description: A feedback message with a code and human-readable description.
      type: object
      properties:
        code:
          description: A short string with a brief explanation about the code reported.
          type: string
        message:
          description: A human-readable message providing more details.
          type: string
        details:
          description: Additional information about the feedback reported.
          type: object
          additionalProperties: true
      required:
        - code
        - message
  headers:
    metadata-etag:
      description: The entity metadata revision.
      schema:
        type: string
        pattern: ^"[A-Fa-f0-9]{64}"$
      examples:
        ETag:
          value: '"9ff2666faa58fabfc282eb90016e7182fe785d37dcdb861c6469cccaec13c876"'
  securitySchemes:
    OAuth2:
      type: oauth2
      description: OAuth 2.0 authentication.
      flows:
        clientCredentials:
          tokenUrl: /core/oauth2/token
          scopes:
            core.users:act-on-behalf-of: Grants access to act on behalf of a user
            core.users:create: Grants access to create users
            core.users:read: Grants access to view users
            core.users:delete: Grants access to delete users
            core.users.metadata:read: Grants access to view user metadata
            core.users.metadata:write: Grants access to modify user metadata
            core.kyc:read: Grants access to view KYC processes
            core.kyc.profile:update: Grants access to update profile KYC process
            core.kyc.address:update: Grants access to update address KYC process
            core.kyc.email:update: Grants access to update email KYC process
            core.kyc.phone:update: Grants access to update phone KYC process
            core.kyc.identity:update: Grants access to update identity KYC process
            core.kyc.proof-of-address:update: Grants access to update proof-of-address KYC process
            core.kyc.customer-due-diligence:update: Grants access to update customer due diligence KYC process
            core.kyc.enhanced-due-diligence:update: Grants access to update enhanced due diligence KYC process
            core.kyc.crypto-risk-assessment:update: Grants access to update crypto risk assessment KYC process
            core.kyc.self-categorization-statement:update: Grants access to update self-categorization statement KYC process
            core.kyc.tax-details:update: Grants access to update tax details KYC process
            core.capabilities:read: Grants access to view user capabilities
            core.terms-of-service:read: Grants access to view terms of service
            core.terms-of-service:accept: Grants access to accept terms of service
            core.files:create: Grants access to create files
            core.files:read: Grants access to view files
            core.files.metadata:read: Grants access to view files metadata
            core.files.metadata:write: Grants access to modify files metadata
            core.accounts:create: Grants access to create accounts
            core.accounts:read: Grants access to view accounts
            core.accounts:update: Grants access to update accounts
            core.accounts:archive: Grants access to archive accounts
            core.accounts:deposit-method: >-
              Grants access to deposit method needed for depositing into
              accounts
            core.accounts:use-test-helpers: Grants access to test helpers of accounts
            core.accounts.metadata:read: Grants access to view accounts metadata
            core.accounts.metadata:write: Grants access to modify accounts metadata
            core.assets:use-test-helpers: Grants access to test helpers of assets
            core.external-accounts:create: Grants access to create external accounts
            core.external-accounts:read: Grants access to view external accounts
            core.external-accounts:update: Grants access to update external accounts
            core.external-accounts:delete: Grants access to delete external accounts
            core.external-accounts.metadata:read: Grants access to view external accounts metadata
            core.external-accounts.metadata:write: Grants access to modify external accounts metadata
            core.transactions:create: Grants access to commit quotes
            core.transactions:read: Grants access to view transactions
            core.transactions.metadata:read: Grants access to view transactions metadata
            core.transactions.metadata:write: Grants access to modify transactions metadata
            core.transactions.requests-for-information:read: Grants access to view transactions requests for information
            core.transactions.requests-for-information:update: Grants access to update transactions requests for information
            core.portfolio:read: >-
              Grants access to view portfolio overview, performance, and
              historical balance
            core.statements:read: Grants access to read statements
            core.webhooks:management-link: Grants access to create webhook management links

````