API — Segments

Segmentos dinâmicos de contatos baseados em critérios.

Para conceitos, veja Segmentos.

Endpoints

Método	Endpoint	Ação
`GET`	`/api/v1/accounts/{id}/segments`	Lista segmentos
`POST`	`/api/v1/accounts/{id}/segments`	Cria segmento
`GET`	`/api/v1/accounts/{id}/segments/{id}`	Detalhes
`PATCH`	`/api/v1/accounts/{id}/segments/{id}`	Atualizar critérios
`DELETE`	`/api/v1/accounts/{id}/segments/{id}`	Excluir
`GET`	`/api/v1/accounts/{id}/segments/{id}/members`	Contatos do segmento
`GET`	`/api/v1/accounts/{id}/segments/{id}/export_members`	Exportar CSV
`POST`	`/api/v1/accounts/{id}/segments/{id}/add_contacts`	Acrescenta contatos — só em lista estática
`POST`	`/api/v1/accounts/{id}/segments/{id}/remove_contacts`	Tira contatos — só em lista estática
`POST`	`/api/v1/accounts/{id}/segments/{id}/preview_rules`	Simula quantos entram, sem gravar
`POST`	`/api/v1/accounts/{id}/segments/combine`	Junta segmentos (união, interseção, diferença)

Tipos: Lista vs Segmento dinâmico

Cada segmento tem um campo segment_type:

Type	Comportamento
`list`	Lista estática. Membership fixo, sem regras. Adicionar/remover manual ou via import. Não esvazia ao editar.
`dynamic`	Segmento dinâmico. Dirigido por filtros em `query.payload`. Contatos entram/saem automaticamente conforme regras.

Regra nova segment_membership permite combinar: “Pertence à lista X” pode ser usado como condição dentro de outro segmento dinâmico.

Campos

{
  "id": 12,
  "name": "VIPs de SP",
  "description": "Para a campanha mensal de reativação",
  "segment_type": "dynamic",
  "active": true,
  "contacts_count": 145,
  "created_by_id": 7,
  "query": {
    "payload": [
      {
        "attribute_key": "labels",
        "filter_operator": "contains",
        "values": ["vip"]
      },
      {
        "attribute_key": "city",
        "filter_operator": "equal_to",
        "values": ["São Paulo"],
        "query_operator": "and"
      }
    ]
  },
  "created_at": "2026-01-15T10:00:00.000Z",
  "updated_at": "2026-09-22T14:30:00.000Z"
}

Três nomes que costumam confundir:

Você esperava	O campo é
`filters`	`query.payload`
`operator`	`filter_operator`
`shared`	não existe — segmento é da conta

A resposta vem embrulhada em payload: { "payload": { "id": 12, ... } }.

Criar segmento

Os campos vão dentro de um objeto segment:

curl -X POST "https://app.smart2.com.br/api/v1/accounts/1/segments" \
  -H "api_access_token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "segment": {
      "name": "Inativos há 90 dias",
      "segment_type": "dynamic",
      "query": {
        "payload": [
          {
            "attribute_key": "last_activity_at",
            "filter_operator": "days_before",
            "values": [90]
          }
        ]
      }
    }
  }'

Sem segment_type, o tipo é deduzido: com regras vira dinâmico, sem regras vira lista estática.

Segmento dinâmico não nasce preenchido — o cálculo roda em segundo plano depois da criação. contacts_count vem zero na resposta e enche em seguida.

Lista estática

# criar
curl -X POST ".../segments" -H "Content-Type: application/json" \
  -d '{ "segment": { "name": "Feira de outubro", "segment_type": "list" } }'

# acrescentar
curl -X POST ".../segments/17/add_contacts" -H "Content-Type: application/json" \
  -d '{ "contact_ids": [4521, 4522] }'

# tirar
curl -X POST ".../segments/17/remove_contacts" -H "Content-Type: application/json" \
  -d '{ "contact_ids": [4522] }'

Em segmento dinâmico essas duas ações são recusadas: lá quem decide quem entra é a regra.

Listar contatos do segmento

GET /api/v1/accounts/1/segments/12/members

Útil pra alimentar campanha (pelo painel) ou exportar pra fora.

Caso de uso

Reativação automática — busca segmento via API e dispara mensagem proativa:

# A cada semana, processar segmento
segment_contacts = requests.get(
    f"{BASE_URL}/segments/12/members",
    headers=HEADERS
).json()['payload']

for contact in segment_contacts:
    # Criar conversa proativa
    # Disparar template HSM
    ...