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

# Listar campos personalizados

> Retorna todos os campos personalizados da organização.

Campos personalizados estendem contatos, empresas e negócios com dados próprios da sua operação.

## Endpoint

```
GET /v1/custom-fields
```

**Escopo necessário:** `read:custom_fields`

## Parâmetros de query

| Parâmetro | Tipo   | Descrição                                         |
| --------- | ------ | ------------------------------------------------- |
| `entity`  | string | Filtra por entidade: `contact`, `company`, `deal` |

## Exemplo de requisição

```bash theme={null}
curl "https://api.socialsell.ai/v1/custom-fields?entity=contact" \
  -H "Authorization: Bearer sk_live_..."
```

## Exemplo de resposta

```json theme={null}
{
  "data": [
    {
      "id": "664n9o0p1q2r3s4t5u6v7w8x",
      "key": "cpf",
      "label": "CPF",
      "type": "text",
      "entity": "contact",
      "options": [],
      "default_value": null,
      "required": false,
      "is_active": true
    }
  ],
  "meta": { "total": 1, "has_more": false }
}
```

## Objeto campo personalizado

| Campo           | Tipo    | Descrição                                |
| --------------- | ------- | ---------------------------------------- |
| `id`            | string  | ID do campo                              |
| `key`           | string  | Chave única (imutável após criação)      |
| `label`         | string  | Rótulo de exibição                       |
| `type`          | string  | Tipo do campo                            |
| `entity`        | string  | Entidade: `contact`, `company` ou `deal` |
| `options`       | array   | Opções para `select`/`multiselect`       |
| `default_value` | any     | Valor padrão                             |
| `required`      | boolean | Se é obrigatório                         |
| `is_active`     | boolean | Se está ativo                            |

<Tip>
  Os valores dos campos personalizados são lidos e gravados via o objeto `custom_fields` (chave → valor) em contatos, empresas e negócios.
</Tip>