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

# Create a contact custom field

> Create a workspace-scoped text custom field for contacts. Use the returned field name in contact create/update payloads and outreach templates. This stores literal text supplied by users or integrations; it does not create or run an AI variable.

    > **Required scope:** `CONTACTS_WRITE`
    >
    > **Rate limit:** 30 requests per minute



## OpenAPI

````yaml https://openapi.enginy.ai/definitions.json post /v1/contacts/fields
openapi: 3.1.0
info:
  title: Enginy API
  version: 1.0.0
  description: Public API for Enginy platform
servers:
  - url: https://openapi.enginy.ai
    description: Configured server
security: []
tags:
  - name: AI Variables
    description: >-
      Manage AI variables and discover the entity fields you can reference in
      prompts and entity requests.
  - name: Inbox
    description: >-
      Inbox endpoints for listing contact threads, reading thread messages,
      managing tags, and sending manual replies.
  - name: Workflows
    description: >-
      Build, validate, publish, run, and inspect advanced (graph) workflows,
      plus the block/condition catalog needed to author a workflow plan.
paths:
  /v1/contacts/fields:
    post:
      tags:
        - Contacts
      summary: Create a contact custom field
      description: >-
        Create a workspace-scoped text custom field for contacts. Use the
        returned field name in contact create/update payloads and outreach
        templates. This stores literal text supplied by users or integrations;
        it does not create or run an AI variable.

            > **Required scope:** `CONTACTS_WRITE`
            >
            > **Rate limit:** 30 requests per minute
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  description: >-
                    Unique field name. It must not conflict with a standard
                    field, AI variable, CRM field, formula field, or another
                    custom field in the workspace.
              required:
                - name
              additionalProperties: false
            examples:
              outreachStatus:
                summary: Create a text field for outreach data
                value:
                  name: Outreach status
      responses:
        '201':
          description: Contact custom field created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - success
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        description: >-
                          Exact field identifier used in prompts (`{fieldName}`)
                          and `fields` query params across the entity endpoints.
                      customFieldId:
                        type: integer
                        exclusiveMinimum: 0
                        description: >-
                          Numeric custom-field identifier. Present only for
                          EMPTY_FIELD fields; use it as emptyFieldId in
                          edit-property workflow blocks.
                      label:
                        type: string
                        description: Human-readable field label.
                      fieldType:
                        type: string
                        enum:
                          - STANDARD
                          - AI_VARIABLE
                          - CRM_FIELD
                          - FORMULA_FIELD
                          - EMPTY_FIELD
                        description: >-
                          Whether this is a standard field or a smart field
                          type.
                      entity:
                        type: string
                        enum:
                          - CONTACT
                          - COMPANY
                        description: Entity the field belongs to.
                      dataType:
                        type: string
                        description: >-
                          Underlying data type. Standard fields report their
                          storage type (`text`, `integer`, `boolean`, …);
                          EMPTY_FIELD custom properties report their configured
                          type (`text`, `number`, `date`, `boolean`,
                          `picklist`).
                      options:
                        type: array
                        items:
                          type: object
                          properties:
                            label:
                              type: string
                            value:
                              type: string
                          required:
                            - label
                            - value
                        description: >-
                          Allowed choices for a `picklist` EMPTY_FIELD. Present
                          only for picklist custom properties; an edit-property
                          block must send one of these `value` strings as
                          emptyFieldValue.
                      editable:
                        type: boolean
                        description: >-
                          Whether this field is editable via the entity update
                          endpoint.
                      searchable:
                        type: boolean
                        description: Whether this field is searchable in Enginy.
                      sortable:
                        type: boolean
                        description: Whether this field is sortable in Enginy.
                      importable:
                        type: boolean
                        description: Whether this field is importable in Enginy.
                      exportable:
                        type: boolean
                        description: Whether this field is exportable in Enginy.
                      promptReference:
                        type: string
                        description: >-
                          Copy-paste-ready placeholder syntax for prompts.
                          Example: `{firstName}`.
                    required:
                      - id
                      - label
                      - fieldType
                      - entity
                      - dataType
                      - editable
                      - searchable
                      - sortable
                      - importable
                      - exportable
                      - promptReference
                required:
                  - status
                  - message
                  - data
        '400':
          description: >-
            Bad request - name is missing, empty, or the body contains
            unsupported fields
        '409':
          description: Conflict - the field name is already in use in this workspace
      security:
        - apiKey: []
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key

````