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

# Update a custom field

> Update a definition. `entityType`, `key` and `fieldType` are immutable. Set `isArchived: true` to retire a field without losing stored values.



## OpenAPI

````yaml https://app.alvahq.com/api/v1/openapi patch /api/v1/custom-field/{id}
openapi: 3.1.0
info:
  title: Alva API
  version: 1.0.0
  description: >
    The Alva API provides programmatic access to your CRM data. Use it to
    integrate Alva with other applications, build custom workflows, or connect
    via platforms like Zapier.


    ## Authentication


    All API requests require a valid API key passed as a Bearer token:


    ```

    Authorization: Bearer alva_sk_your_api_key_here

    ```


    API keys can be created and managed in **Settings > Developer** within the
    Alva application.


    ## Rate Limiting


    API requests are rate limited to **100 requests per minute** per API key.
    Rate limit information is included in response headers:


    - `X-RateLimit-Limit` - Maximum requests per minute

    - `X-RateLimit-Remaining` - Requests remaining in current window

    - `X-RateLimit-Reset` - Unix timestamp when the window resets


    ## Pagination


    List endpoints support pagination via query parameters:


    - `page` - Page number (default: 1)

    - `limit` - Items per page (default: 25, max: 100)


    ## Sorting


    List endpoints support sorting:


    - `sort` - Sort field and direction, e.g. `sort=createdAt:desc`


    ## Errors


    All errors follow a consistent format:


    ```json

    {
      "error": "Error Type",
      "message": "Human-readable description",
      "details": { "field": ["Validation message"] }
    }

    ```
  contact:
    name: Alva Support
    url: https://alva.ai
servers:
  - url: https://app.alvahq.com
    description: Current environment
security:
  - bearerAuth: []
tags:
  - name: Companies
    description: Manage companies in your CRM
  - name: Contacts
    description: Manage contacts and people
  - name: Deals
    description: Manage sales deals and pipeline
  - name: Activities
    description: Log and track activities (calls, meetings, emails, etc.)
  - name: Pipeline
    description: Pipeline stages and methodology metadata
  - name: Custom Fields
    description: Define custom fields on companies and contacts
  - name: Email Templates
    description: >-
      Manage email templates and template groups. Use {{company.custom.<key>}}
      merge tags in subject and body.
  - name: Account
    description: API key, account members and company tags
  - name: BDR Agents
    description: List BDR agents and assign a company to one
paths:
  /api/v1/custom-field/{id}:
    patch:
      tags:
        - Custom Fields
      summary: Update a custom field
      description: >-
        Update a definition. `entityType`, `key` and `fieldType` are immutable.
        Set `isArchived: true` to retire a field without losing stored values.
      operationId: updateCustomField
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The custom field ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCustomField'
      responses:
        '200':
          description: CustomField
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    description: Human-readable confirmation of the action.
                  data:
                    $ref: '#/components/schemas/CustomField'
                  resource:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorised'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  schemas:
    UpdateCustomField:
      type: object
      description: All fields optional. entityType, key and fieldType cannot be changed.
      properties:
        label:
          type: string
        options:
          type: array
          items:
            type: string
        required:
          type: boolean
        defaultValue:
          nullable: true
        helpText:
          type: string
          nullable: true
        sortOrder:
          type: integer
        isArchived:
          type: boolean
      example:
        label: Account Tier
        isArchived: false
    CustomField:
      type: object
      properties:
        id:
          type: string
          format: uuid
        entityType:
          type: string
          enum:
            - company
            - contact
        key:
          type: string
          example: account_tier
          description: >-
            Stable machine key (immutable). Use in merge fields as
            {{company.custom.<key>}}.
        label:
          type: string
          example: Account Tier
        fieldType:
          type: string
          enum:
            - text
            - textarea
            - number
            - boolean
            - date
            - datetime
            - select
            - multi_select
            - url
            - email
            - phone
            - currency
        options:
          type: array
          items:
            type: string
          description: Allowed values for select / multi_select
        required:
          type: boolean
        defaultValue:
          nullable: true
          description: Typed default value (matches fieldType)
        helpText:
          type: string
          nullable: true
        sortOrder:
          type: integer
        isArchived:
          type: boolean
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        details:
          type: object
          nullable: true
  responses:
    Unauthorised:
      description: Authentication failed - invalid, expired, or revoked API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Unauthorised
            message: Invalid or revoked API key
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Not Found
            message: Company with id 'xxx' not found
    ValidationError:
      description: Request body validation failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Unprocessable Entity
            message: Validation failed
            details:
              name:
                - Name is required
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'API key from Settings > Developer. Format: alva_sk_...'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.