> For the complete documentation index, see [llms.txt](https://outboundpro.gitbook.io/api-v1/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://outboundpro.gitbook.io/api-v1/list/buscar-listas.md).

# Buscar listas

## Buscar listas com filtros

> Filtra listas por nome (parcial), tipo, visibilidade (públicas/privadas),\
> usuário dono, prevendedor designado ou intervalo de cadastro.\
> \
> Variante mais flexível de \`/list/list\` — quando precisa \*\*filtrar\*\* em vez de\
> só paginar tudo.\
> \
> \### Quando usar\
> \- \*\*Picker com autocomplete\*\* — usuário digita "campanha Q1" no CRM, sistema\
>   chama \`/list/search?nome=campanha%20Q1\` pra sugerir listas existentes.\
> \- \*\*Relatório por dono\*\* — auditoria de listas criadas por SDR específico\
>   (filtra por \`usuario\_id\`).\
> \- \*\*Limpeza periódica\*\* — busca listas antigas (cadastro > 6 meses) sem\
>   movimentação pra arquivar/deletar.\
> \
> \### Casos de uso reais\
> \- \*\*Bot Slack\*\*: comando \`/listas-leo\` no Slack busca listas do usuário Leo\
>   ordenadas por data, manda preview no canal.\
> \- \*\*Auditoria mensal\*\*: cron mensal busca listas órfãs (sem usuário responsável\
> &#x20; ativo) e notifica gestor pra realocar.<br>

```json
{"openapi":"3.0.3","info":{"title":"OutboundPro API","version":"2.0.0"},"tags":[{"name":"List","description":"**Listas de leads** — agrupamentos arbitrários que você cria para\norganizar prospecção (ex.: \"E-commerces SP\", \"Tecnologia ENT\", \"Black Friday 2026\").\n\nListas podem ser **públicas** (compartilhadas com todo o cliente) ou\n**privadas** (só você), ter **prevendedor** designado, cor customizada,\ne **seguidores** (usuários que recebem notificação de movimento).\n\n### Operações suportadas\n- CRUD completo (list, search, create, edit, delete).\n- Exclusão é **lógica** (soft delete; `lis_excluida = 'S'`).\n- Buscar com filtros: nome, tipo, público/privado, dono, prevendedor, período.\n"}],"servers":[{"url":"https://app.outboundpro.com.br/api","description":"Produção"}],"security":[{"TokenAuth":[]}],"components":{"securitySchemes":{"TokenAuth":{"type":"apiKey","in":"header","name":"Token","description":"Chave privada do cliente (`cli_chave_privada`). Formato UUID v4\n(36 caracteres com hífens). Aceita header em qualquer case\n(`Token`, `token`, `TOKEN`).\n"}},"schemas":{"PaginacaoEnvelope":{"type":"object","required":["response","total","pagina","limite","paginas"],"properties":{"response":{"type":"string","enum":["success"]},"total":{"type":"integer","description":"Total geral (ignora paginação)."},"pagina":{"type":"integer","minimum":1},"limite":{"type":"integer","minimum":1,"maximum":100},"paginas":{"type":"integer","description":"Total de páginas considerando `limite` atual."}}},"Lista":{"type":"object","properties":{"id":{"type":"integer"},"codigo_ficticio":{"type":"integer","description":"Código curto para exibição (não use em joins; use `id`)."},"nome":{"type":"string"},"publica":{"type":"string","enum":["S","N"],"description":"S = compartilhada com todo o cliente, N = privada."},"cor_fundo":{"type":"string"},"cor_texto":{"type":"string"},"tipo":{"type":"string"},"prevendedor_id":{"type":"integer","nullable":true,"description":"Usuário responsável pela prospecção da lista."},"seguidores":{"type":"array","description":"Usuários que recebem notificação quando lead é movido na lista.","items":{"type":"object","properties":{"id":{"type":"integer"},"nome":{"type":"string"},"email":{"type":"string","format":"email"}}}},"data_cadastro":{"type":"string","format":"date-time"}}},"ErrorResponse":{"type":"object","required":["response"],"properties":{"response":{"type":"string","enum":["error"]},"mensagem":{"type":"string","description":"Descrição do erro em pt-BR. Família Contact usa `message` (legado)."},"message":{"type":"string","description":"Equivalente inglês de `mensagem`, usado pela família Contact."}}}},"responses":{"Unauthorized":{"description":"Token ausente, inválido ou cliente inativo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/list/search":{"get":{"tags":["List"],"summary":"Buscar listas com filtros","operationId":"listSearch","description":"Filtra listas por nome (parcial), tipo, visibilidade (públicas/privadas),\nusuário dono, prevendedor designado ou intervalo de cadastro.\n\nVariante mais flexível de `/list/list` — quando precisa **filtrar** em vez de\nsó paginar tudo.\n\n### Quando usar\n- **Picker com autocomplete** — usuário digita \"campanha Q1\" no CRM, sistema\n  chama `/list/search?nome=campanha%20Q1` pra sugerir listas existentes.\n- **Relatório por dono** — auditoria de listas criadas por SDR específico\n  (filtra por `usuario_id`).\n- **Limpeza periódica** — busca listas antigas (cadastro > 6 meses) sem\n  movimentação pra arquivar/deletar.\n\n### Casos de uso reais\n- **Bot Slack**: comando `/listas-leo` no Slack busca listas do usuário Leo\n  ordenadas por data, manda preview no canal.\n- **Auditoria mensal**: cron mensal busca listas órfãs (sem usuário responsável\n  ativo) e notifica gestor pra realocar.\n","parameters":[{"in":"query","name":"pagina","schema":{"type":"integer","default":1,"minimum":1}},{"in":"query","name":"limite","schema":{"type":"integer","default":50,"minimum":1,"maximum":100}},{"in":"query","name":"ordenacao","schema":{"type":"string","default":"lis_data_cadastro"}},{"in":"query","name":"direcao","schema":{"type":"string","enum":["ASC","DESC"],"default":"DESC"}},{"in":"query","name":"id","schema":{"type":"integer"}},{"in":"query","name":"nome","schema":{"type":"string"},"description":"Busca parcial case-insensitive."},{"in":"query","name":"tipo","schema":{"type":"string"}},{"in":"query","name":"publica","schema":{"type":"string","enum":["true","false","1","0"]}},{"in":"query","name":"usuario_id","schema":{"type":"integer"}},{"in":"query","name":"prevendedor_id","schema":{"type":"integer"}},{"in":"query","name":"data_inicial","schema":{"type":"string","format":"date"}},{"in":"query","name":"data_final","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Listas encontradas.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginacaoEnvelope"},{"type":"object","properties":{"listas":{"type":"array","items":{"$ref":"#/components/schemas/Lista"}}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```