Propriedades customizadas

Base path: /api/v1/properties Scope: properties:read (apenas leitura via API)

Propriedades customizadas são campos extras que cada tenant define no CRM (ex: “Cargo”, “Indústria”, “Origem do lead”) além dos campos padrão. Quando você lê/escreve um contato, esses campos aparecem em customProperties: { propertyId: value }.

Pra integrar, sua integração precisa descobrir as propriedades existentes — daí esse endpoint. Não dá pra criar propriedades via API (só admin no CRM).

Lista propriedades

GET /api/v1/properties?objectType=contact

Scope: properties:read

Param	Tipo	Obrigatório	Descrição
objectType	contact | company | deal	✅	Tipo de objeto

curl "https://app.indutivacrm.com.br/api/v1/properties?objectType=contact" \
  -H "X-API-Key: crm_live_..."

[
  {
    "id": "ckl4pr01...",
    "objectType": "contact",
    "internalName": "cargo",
    "label": "Cargo",
    "type": "text",
    "group": "Profissional",
    "displayOrder": 0,
    "isDefaultInForm": true
  },
  {
    "id": "ckl4pr02...",
    "objectType": "contact",
    "internalName": "industria",
    "label": "Indústria",
    "type": "select",
    "group": "Profissional",
    "displayOrder": 1,
    "isDefaultInForm": false,
    "options": [
      { "value": "manufatura", "label": "Manufatura" },
      { "value": "varejo", "label": "Varejo" },
      { "value": "servicos", "label": "Serviços" }
    ]
  }
]

Tipos de propriedade (type)

Tipo	Aceita
text	String curta (single line)
textarea	Texto longo (multi line)
email	String validada como email
phone	Telefone (normalizado E.164)
url	URL completa
number	Número (int ou float)
date	Data ISO YYYY-MM-DD
datetime	Data + hora ISO 8601
select	Uma opção de options
multi_select	Array de opções de options
boolean	true / false

Usando ao criar/atualizar

Ao mandar customProperties em POST /contacts (ou companies/deals), use o id da propriedade (não o internalName) como chave:

curl -X POST https://app.indutivacrm.com.br/api/v1/contacts \
  -H "X-API-Key: crm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Maria",
    "email": "maria@acme.com.br",
    "customProperties": {
      "ckl4pr01...": "Diretora Comercial",
      "ckl4pr02...": "manufatura"
    }
  }'

Mapeie por internalName

Pra resiliência, é boa prática cachear localmente um mapa internalName → id ao iniciar a integração:

const props = await api('/properties?objectType=contact')
const propMap = Object.fromEntries(props.map(p => [p.internalName, p.id]))

// Depois usa o nome amigável:
await api('/contacts', {
  method: 'POST',
  body: {
    firstName: 'Maria',
    customProperties: {
      [propMap.cargo]: 'Diretora',
      [propMap.industria]: 'manufatura',
    },
  },
})

internalName é estável entre tenants do mesmo template; id é único por tenant.

Erros

Status	error	Cenário
400	validation_failed	objectType ausente ou valor inválido
403	insufficient_scope	Key sem properties:read