> ## 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.

# List Custom Fields

> Retrieve all custom fields defined for your account

<Tip>Use the `groupBy=category` query parameter to get custom fields organized by category for easier management.</Tip>

## Use Cases

* **Display field options**: Show available custom fields in your application UI
* **Integration mapping**: Map external CRM fields to Minimo custom fields
* **Data validation**: Check which fields exist before creating contacts

## Group by Category

Get custom fields organized by category by adding the `groupBy=category` query parameter:

```bash theme={null}
curl --request GET \
  --url 'https://api.minimo.it/public/v1/custom-fields?groupBy=category' \
  --header 'Authorization: Bearer mn-YOUR_CLIENT_ID-YOUR_API_KEY'
```

**Grouped Response:**

```json theme={null}
{
  "data": {
    "groups": [
      {
        "category": "Company Info",
        "fields": [
          { "id": 1, "key": "COMPANY_SIZE", "displayName": "Company Size", "type": "text" },
          { "id": 2, "key": "INDUSTRY", "displayName": "Industry", "type": "select" }
        ]
      },
      {
        "category": "uncategorized",
        "fields": [{ "id": 3, "key": "NOTES", "displayName": "Notes", "type": "text" }]
      }
    ],
    "total": 3
  }
}
```

<Note>Fields without a category are automatically grouped under `uncategorized`.</Note>

## 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                   |

## Common Errors

| Error              | Cause                 | Solution                             |
| ------------------ | --------------------- | ------------------------------------ |
| `unauthorized`     | Invalid API key       | Check Authorization header format    |
| `invalid_group_by` | Invalid groupBy value | Use `category` or omit the parameter |

## Related Endpoints

* **[Create Custom Field](/api-reference/core-data/custom-fields/create)**: Create a new custom field
* **[Create or Update Contact](/api-reference/core-data/contacts/upsert)**: Create and update contacts with custom field values


## OpenAPI

````yaml get /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
    get:
      summary: List all custom fields
      description: >-
        Retrieve all custom fields defined for your account. Use
        groupBy=category to get fields organized by category.
      operationId: listCustomFields
      parameters:
        - name: groupBy
          in: query
          required: false
          description: Group results by specified field (only 'category' is supported)
          schema:
            type: string
            enum:
              - category
      responses:
        '200':
          description: Successful response with custom fields
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    oneOf:
                      - type: array
                        items:
                          $ref: '#/components/schemas/CustomField'
                      - $ref: '#/components/schemas/CustomFieldGroupedResponse'
        '400':
          description: Invalid or missing authentication token
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Missing API client ID or API key
      security:
        - bearerAuth: []
components:
  schemas:
    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
    CustomFieldGroupedResponse:
      type: object
      properties:
        groups:
          type: array
          items:
            type: object
            properties:
              category:
                type: string
                description: Category name or "uncategorized"
              fields:
                type: array
                items:
                  $ref: '#/components/schemas/CustomField'
        total:
          type: integer
          description: Total number of custom fields
      example:
        groups:
          - category: Company Info
            fields:
              - id: 1
                key: COMPANY_SIZE
                displayName: Company Size
                type: text
          - category: uncategorized
            fields:
              - id: 2
                key: NOTES
                displayName: Notes
                type: text
        total: 2
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: mn-API_CLIENT_ID-API_KEY

````