Listar Campos Personalizados
GET/external/v1/custom-fieldsRetorna as definições de campos personalizados da sua conta. field_key é a chave a usar dentro de custom_fields ao criar ou atualizar uma oportunidade ou um contato; options lista os valores aceitos pelos campos dropdown, multiselect e radio.
Autenticação
Requer permissão custom_fields:read.
Parâmetros de Query
| Parâmetro | Tipo | Padrão | Descrição |
|---|---|---|---|
entity | string | - | Só os campos de uma entidade: contact, opportunity ou company |
is_active | boolean | - | true retorna só os campos ativos, false só os arquivados |
Requisição
bash
curl --request GET \
--url "https://app.getraze.com/external/v1/custom-fields?entity=opportunity" \
--header "X-API-Key: YOUR_API_KEY"javascript
const axios = require('axios');
const response = await axios.get('https://app.getraze.com/external/v1/custom-fields', {
headers: { 'X-API-Key': 'YOUR_API_KEY' },
params: { entity: 'opportunity' }
});
console.log(response.data);python
import requests
response = requests.get(
'https://app.getraze.com/external/v1/custom-fields',
headers={'X-API-Key': 'YOUR_API_KEY'},
params={'entity': 'opportunity'}
)
print(response.json())Resposta
json
{
"success": true,
"data": [
{
"id": "cf_01",
"entity_type": "opportunity",
"field_key": "origem_lead",
"label": "Origem do lead",
"field_type": "dropdown",
"options": ["Indicação", "Evento", "Site"],
"is_required": false,
"placeholder": null,
"help_text": "Por onde o lead nos conheceu",
"position": 0,
"is_active": true,
"created_at": "2026-03-02T14:00:00Z",
"updated_at": "2026-03-02T14:00:00Z"
},
{
"id": "cf_02",
"entity_type": "opportunity",
"field_key": "faturamento_anual",
"label": "Faturamento anual",
"field_type": "number",
"options": [],
"is_required": false,
"placeholder": null,
"help_text": null,
"position": 1,
"is_active": true,
"created_at": "2026-03-02T14:05:00Z",
"updated_at": "2026-03-02T14:05:00Z"
}
]
}Campos de Resposta
| Campo | Tipo | Descrição |
|---|---|---|
id | string | Identificador da definição |
entity_type | string | contact, opportunity ou company |
field_key | string | A chave a usar em custom_fields |
label | string | Nome exibido no produto |
field_type | string | text, memo, number, date, dropdown, multiselect, radio, checkbox, phone, email ou url |
options | array | Valores aceitos por dropdown, multiselect e radio; vazio nos demais tipos |
is_required | boolean | Obrigatório nos formulários do produto |
placeholder / help_text | string | Dicas do formulário (nullable) |
position | integer | Ordem no formulário |
is_active | boolean | Campos arquivados mantêm os valores gravados, mas não aparecem mais |
Gravando campos personalizados
json
{
"custom_fields": {
"origem_lead": "Evento",
"faturamento_anual": 120000
}
}custom_fields faz merge com os valores existentes: as chaves que você não envia são mantidas. Os valores são gravados como enviados, sem validação contra a definição, então siga o tipo do campo.