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

# Create Field

> Create a custom field. The field's `key` is what you use in the `fields` and `companyFields` maps of other endpoints.

> **Request access.** This endpoint is not enabled by default, contact the Conversion team to request access. Calls from accounts without it return `403 export_not_enabled`.



## OpenAPI

````yaml /openapi.json post /v2/fields
openapi: 3.1.0
info:
  title: Conversion API
  version: 2.0.0
  description: >-
    The Conversion API lets you programmatically manage contacts, track custom
    events, and manage their associated data.
servers:
  - url: https://pub-api.conversion.ai/api
security:
  - apiKey: []
paths:
  /v2/fields:
    post:
      summary: Create Field
      description: >-
        Create a custom field. The field's `key` is what you use in the `fields`
        and `companyFields` maps of other endpoints.


        > **Request access.** This endpoint is not enabled by default, contact
        the Conversion team to request access. Calls from accounts without it
        return `403 export_not_enabled`.
      operationId: createField
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - label
                - objectType
                - dataType
              properties:
                label:
                  type: string
                  description: The human-readable display name of the field.
                  examples:
                    - Lead Score
                key:
                  type: string
                  description: >-
                    The field key used in the `fields` and `companyFields` maps
                    of other endpoints. Optional — derived from `label` when
                    omitted.


                    Must be unique across your account's fields: creating a
                    field with a key that already exists returns a `400`
                    `invalid_field` error.
                  examples:
                    - lead_score
                objectType:
                  type: string
                  enum:
                    - CONTACT
                    - COMPANY
                    - OPPORTUNITY
                    - CAMPAIGN_MEMBER
                  description: >-
                    The object the field belongs to (case-insensitive). An
                    unsupported value returns an `invalid_object_type` error.
                dataType:
                  type: string
                  enum:
                    - STRING
                    - NUMBER
                    - BOOLEAN
                    - DATE
                    - DATETIME
                  description: The data type of the field's value (case-insensitive).
            examples:
              create-contact-field:
                summary: Create a contact field
                value:
                  label: Lead Score
                  objectType: CONTACT
                  dataType: NUMBER
              create-with-explicit-key:
                summary: Create with an explicit key
                value:
                  key: renewal_date
                  label: Renewal Date
                  objectType: COMPANY
                  dataType: DATE
      responses:
        '200':
          description: Field created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    required:
                      - field
                    properties:
                      field:
                        type: object
                        required:
                          - key
                          - label
                          - objectType
                          - dataType
                        properties:
                          key:
                            type: string
                            description: >-
                              The field key used in the `fields` and
                              `companyFields` maps of other endpoints.
                            examples:
                              - lead_score
                          label:
                            type: string
                            description: The human-readable display name of the field.
                            examples:
                              - Lead Score
                          objectType:
                            type: string
                            enum:
                              - CONTACT
                              - COMPANY
                              - OPPORTUNITY
                              - CAMPAIGN_MEMBER
                            description: The object this field belongs to.
                          dataType:
                            type: string
                            enum:
                              - STRING
                              - NUMBER
                              - BOOLEAN
                              - DATE
                              - DATETIME
                            description: The data type of the field's value.
              examples:
                created:
                  summary: Field created
                  value:
                    data:
                      field:
                        key: lead_score
                        label: Lead Score
                        objectType: CONTACT
                        dataType: NUMBER
        '400':
          description: The request was malformed or contained invalid data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid-object-type:
                  summary: Unsupported object type
                  value:
                    error:
                      code: invalid_object_type
                      message: >-
                        unsupported object type 'DEAL'; supported values:
                        [CONTACT COMPANY OPPORTUNITY CAMPAIGN_MEMBER]
                duplicate-key:
                  summary: Field key already exists
                  value:
                    error:
                      code: invalid_field
                      message: a field with key 'lead_score' already exists
        '401':
          description: Authentication failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unauthorized:
                  summary: Missing or invalid API key
                  value:
                    error:
                      code: unauthorized
                      message: API key is required
        '403':
          description: This endpoint is not enabled for this account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not-enabled:
                  summary: Endpoint not enabled
                  value:
                    error:
                      code: export_not_enabled
                      message: business is not authorized to use this endpoint
        '500':
          description: An unexpected server error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                internal:
                  summary: Internal error
                  value:
                    error:
                      code: internal_error
                      message: failed to create field
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: A machine-readable error code.
              examples:
                - invalid_email
            message:
              type: string
              description: A human-readable error description.
              examples:
                - 'invalid email format: not-an-email'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Your Conversion API key. Found in **Settings > Integrations** in the
        dashboard. Format: `sk_live_<key_id>_<secret>`.

````