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

# Create Custom Field

> Create a new custom field to store additional contact data

<Tip>
  Custom fields allow you to define and organize additional attributes for your contacts beyond the standard fields
  (email, phone, name).
</Tip>

## Use Cases

* **Lead qualification**: Store lead score, source, or stage
* **Segmentation**: Categorize contacts by industry, plan, or region
* **Personalization**: Store preferences for personalized messaging
* **Integration sync**: Map external CRM fields to Minimo

## Field Types

| Type       | Description                   |
| ---------- | ----------------------------- |
| `text`     | Free text input               |
| `number`   | Numeric value                 |
| `boolean`  | True/false                    |
| `date`     | Date value                    |
| `datetime` | Date and time                 |
| `select`   | Single selection from options |
| `json`     | JSON object                   |

## Best Practices

<AccordionGroup>
  <Accordion title="Use Consistent Naming">
    Use `SNAKE_CASE` for keys (e.g., `COMPANY_SIZE`, `LEAD_SOURCE`). Keys are automatically uppercased.
  </Accordion>

  {' '}

  <Accordion title="Organize with Categories">
    Group related fields using categories like "Company Info", "Lead Data", "Preferences" for better organization.
  </Accordion>

  <Accordion title="Plan Field Types">
    Choose the right type for your data. Use `number` for numeric values, `date` for dates, and `select` for predefined options.
  </Accordion>
</AccordionGroup>

## Common Errors

| Error                | Cause                    | Solution                           |
| -------------------- | ------------------------ | ---------------------------------- |
| `key already exists` | Duplicate key in account | Use a different key name           |
| `validation_error`   | Missing required fields  | Include key, displayName, and type |
| `unauthorized`       | Invalid API key          | Check Authorization header         |

## Code Examples

<AccordionGroup>
  <Accordion title="JavaScript">
    ```javascript theme={null}
    const response = await fetch('https://api.minimo.it/public/v1/custom-fields', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer mn-YOUR_CLIENT_ID-YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        key: 'LEAD_SOURCE',
        displayName: 'Lead Source',
        type: 'select',
        category: 'Lead Data'
      })
    });
    const { data } = await response.json();
    console.log(data);
    ```
  </Accordion>

  <Accordion title="Python">
    ```python theme={null}
    import requests

    headers = {
        'Authorization': 'Bearer mn-YOUR_CLIENT_ID-YOUR_API_KEY',
        'Content-Type': 'application/json'
    }

    response = requests.post(
        'https://api.minimo.it/public/v1/custom-fields',
        headers=headers,
        json={
            'key': 'LEAD_SOURCE',
            'displayName': 'Lead Source',
            'type': 'select',
            'category': 'Lead Data'
        }
    )
    print(response.json())
    ```
  </Accordion>
</AccordionGroup>

## Related Endpoints

* **[List Custom Fields](/api-reference/core-data/custom-fields/list)**: Retrieve all custom fields
* **[Create or Update Contact](/api-reference/core-data/contacts/upsert)**: Create and update contacts with custom field values


## OpenAPI

````yaml post /public/v1/custom-fields
openapi: 3.1.0
info:
  title: API Documentation
  description: Documentation for transactional and subscribe APIs
  version: 1.0.0
servers:
  - url: https://app.minimo.it
security:
  - bearerAuth: []
paths:
  /public/v1/custom-fields:
    servers:
      - url: https://api.minimo.it
    post:
      summary: Create a custom field
      description: Create a new custom field to store additional contact data.
      operationId: createCustomField
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomFieldRequest'
            example:
              key: COMPANY_SIZE
              displayName: Company Size
              type: text
              category: Company Info
      responses:
        '200':
          description: Custom field created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/CustomField'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Missing required fields
        '409':
          description: Custom field with this key already exists
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Custom field with key "COMPANY_SIZE" already exists
      security:
        - bearerAuth: []
components:
  schemas:
    CreateCustomFieldRequest:
      type: object
      required:
        - key
        - displayName
        - type
      properties:
        key:
          type: string
          description: Unique identifier (will be uppercased)
          example: COMPANY_SIZE
        displayName:
          type: string
          description: Human-readable label
          example: Company Size
        type:
          type: string
          description: Field type
          enum:
            - text
            - number
            - boolean
            - date
            - datetime
            - select
            - json
          example: text
        category:
          type: string
          description: Category for grouping fields
          example: Company Info
        acceptableValues:
          type: object
          description: Acceptable values for select/enum types
        metadata:
          type: object
          description: Additional metadata
        visibility:
          type: boolean
          description: Whether field is visible in UI
          default: false
    CustomField:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier
        key:
          type: string
          description: Unique key (uppercase)
        displayName:
          type: string
          description: Human-readable label
        type:
          type: string
          description: Field type
          enum:
            - text
            - number
            - boolean
            - date
            - datetime
            - select
            - json
        category:
          type: string
          nullable: true
          description: Category for grouping
        acceptableValues:
          type: object
          nullable: true
          description: Acceptable values for select types
        metadata:
          type: object
          nullable: true
          description: Additional metadata
        visibility:
          type: boolean
          description: Whether field is visible in UI
        source:
          type: string
          nullable: true
          description: Source of the field
      example:
        id: 1
        key: COMPANY_SIZE
        displayName: Company Size
        type: text
        category: Company Info
        visibility: true
        source: Manual
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: mn-API_CLIENT_ID-API_KEY

````