Filtros

Todos os endpoints de listagem aceitam filtros como parâmetros de consulta. Os filtros são opcionais e combinam entre si com lógica AND: todos os filtros enviados precisam ser satisfeitos para que um registro apareça no resultado. Filtros inválidos retornam 422 com o campo exato que falhou na validação.

Filtros por recurso

`GET /v1/people`

Parâmetro	Tipo	Comparação	Descrição
`full_name`	string	contém (ilike)	Filtra por nome. Não diferencia maiúsculas de minúsculas.
`email`	string	contém (ilike)	Filtra por endereço de email. Match parcial em todos os emails do contato.
`phone`	string	contém (ilike)	Filtra por número de telefone. Match parcial em todos os telefones do contato.
`company_id`	UUID	exato	Retorna apenas pessoas vinculadas à empresa informada.
`has_email`	boolean	exato	`true` para retornar apenas pessoas com email, `false` para pessoas sem email.
`has_phone`	boolean	exato	`true` para retornar apenas pessoas com telefone, `false` para pessoas sem telefone.
`created_after`	ISO 8601	`>=`	Registros criados a partir desta data.
`created_before`	ISO 8601	`<=`	Registros criados até esta data.
`updated_after`	ISO 8601	`>=`	Registros atualizados a partir desta data.
`updated_before`	ISO 8601	`<=`	Registros atualizados até esta data.

# Pessoas da empresa X criadas em 2026
curl "https://api.vendaze.com/v1/people?company_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890&created_after=2026-01-01T00:00:00Z" \
  -H "Authorization: Bearer {access_token}"

`GET /v1/companies`

Parâmetro	Tipo	Comparação	Descrição
`full_name`	string	contém (ilike)	Filtra por razão social. Não diferencia maiúsculas.
`email`	string	exato	Filtra por endereço de email. Match exato em todos os emails da empresa.
`created_after`	ISO 8601	`>=`	Registros criados a partir desta data.
`created_before`	ISO 8601	`<=`	Registros criados até esta data.
`updated_after`	ISO 8601	`>=`	Registros atualizados a partir desta data.
`updated_before`	ISO 8601	`<=`	Registros atualizados até esta data.

# Empresas com "tecnologia" no nome
curl "https://api.vendaze.com/v1/companies?full_name=tecnologia" \
  -H "Authorization: Bearer {access_token}"

`GET /v1/deals`

Parâmetro	Tipo	Comparação	Descrição
`name`	string	contém (ilike)	Filtra pelo nome do negócio. Não diferencia maiúsculas.
`pipeline_id`	UUID	exato	Retorna apenas negócios do pipeline informado.
`stage_id`	UUID	exato	Retorna apenas negócios na etapa informada.
`source`	string	exato	Filtra pela origem (nome do OAuth app que criou o negócio).
`forecast_after`	ISO 8601	`>=`	Negócios com data de previsão igual ou posterior a esta data.
`forecast_before`	ISO 8601	`<=`	Negócios com data de previsão igual ou anterior a esta data.
`created_after`	ISO 8601	`>=`	Registros criados a partir desta data.
`created_before`	ISO 8601	`<=`	Registros criados até esta data.
`updated_after`	ISO 8601	`>=`	Registros atualizados a partir desta data.
`updated_before`	ISO 8601	`<=`	Registros atualizados até esta data.

# Negócios de um pipeline com previsão de fechamento até o fim do ano
curl "https://api.vendaze.com/v1/deals?pipeline_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890&forecast_before=2026-12-31T23:59:59Z" \
  -H "Authorization: Bearer {access_token}"

`GET /v1/pipelines`

O endpoint de listagem de pipelines não suporta filtros por campo. Use order_by e order para controlar a ordenação.

curl "https://api.vendaze.com/v1/pipelines?order_by=name&order=asc" \
  -H "Authorization: Bearer {access_token}"

`GET /v1/tasks`

Parâmetro	Tipo	Comparação	Descrição
`person_id`	UUID	exato	Tarefas vinculadas à pessoa informada.
`company_id`	UUID	exato	Tarefas vinculadas à empresa informada.
`deal_id`	UUID	exato	Tarefas vinculadas ao negócio informado.
`type_id`	UUID	exato	Tarefas do tipo informado.
`priority`	string	exato	`high`, `medium` ou `low`.
`completed`	boolean	exato	`true` para tarefas concluídas, `false` para abertas.
`created_after`	ISO 8601	`>=`	Tarefas criadas a partir desta data.
`created_before`	ISO 8601	`<=`	Tarefas criadas até esta data.

# Tarefas de alta prioridade não concluídas de uma pessoa
curl "https://api.vendaze.com/v1/tasks?person_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890&priority=high&completed=false" \
  -H "Authorization: Bearer {access_token}"

`GET /v1/activities`

Parâmetro	Tipo	Obrigatório	Comparação	Descrição
`entity`	string	Sim	exato	Tipo da entidade vinculada. Valores aceitos: `people`, `companies`, `deals`.
`id`	UUID	Sim	exato	UUID da entidade informada em `entity`.
`created_after`	ISO 8601	Não	`>=`	Atividades criadas a partir desta data.
`created_before`	ISO 8601	Não	`<=`	Atividades criadas até esta data.

entity e id são sempre obrigatórios em conjunto. Requisições sem eles retornam 422.

# Todas as atividades de um negócio
curl "https://api.vendaze.com/v1/activities?entity=deals&id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer {access_token}"

# Atividades de uma pessoa criadas em 2026
curl "https://api.vendaze.com/v1/activities?entity=people&id=c3d4e5f6-a7b8-9012-cdef-123456789012&created_after=2026-01-01T00:00:00Z" \
  -H "Authorization: Bearer {access_token}"

`GET /v1/products`

Parâmetro	Tipo	Comparação	Descrição
`name`	string	contém (ilike)	Filtra por nome do produto. Não diferencia maiúsculas.
`is_active`	boolean	exato	`true` para produtos ativos, `false` para inativos.
`currency`	string	exato	Código ISO 4217 da moeda (ex: `BRL`, `USD`). Filtra por moeda do produto.
`billing_cycle`	string	exato	`monthly`, `yearly`, `weekly`, `daily` ou `one_time`.

# Produtos mensais ativos em BRL
curl "https://api.vendaze.com/v1/products?is_active=true&currency=BRL&billing_cycle=monthly" \
  -H "Authorization: Bearer {access_token}"

`GET /v1/tags`

Parâmetro	Tipo	Comparação	Descrição
`name`	string	contém (ilike)	Filtra por nome da tag. Não diferencia maiúsculas.

curl "https://api.vendaze.com/v1/tags?name=vip" \
  -H "Authorization: Bearer {access_token}"

`GET /v1/lists`

Parâmetro	Tipo	Comparação	Descrição
`name`	string	contém (ilike)	Filtra por nome da lista. Não diferencia maiúsculas.

curl "https://api.vendaze.com/v1/lists?name=leads" \
  -H "Authorization: Bearer {access_token}"

`GET /v1/task-types`

Parâmetro	Tipo	Comparação	Descrição
`title`	string	contém (ilike)	Filtra por título do tipo de tarefa. Não diferencia maiúsculas.

curl "https://api.vendaze.com/v1/task-types?title=ligação" \
  -H "Authorization: Bearer {access_token}"

`GET /v1/custom-fields`

Parâmetro	Tipo	Comparação	Descrição
`show_people`	boolean	exato	`true` para campos que aparecem em pessoas.
`show_companies`	boolean	exato	`true` para campos que aparecem em empresas.
`show_deals`	boolean	exato	`true` para campos que aparecem em negócios.

# Campos adicionais visíveis em pessoas e empresas
curl "https://api.vendaze.com/v1/custom-fields?show_people=true&show_companies=true" \
  -H "Authorization: Bearer {access_token}"

Combinando filtros com paginação

Filtros se combinam normalmente com os parâmetros de paginação (page, per_page, order_by, order). O meta.total na resposta sempre reflete o total de registros que satisfazem os filtros aplicados, não o total geral do workspace.

# Pessoas da empresa X, ordenadas por nome, página 2
curl "https://api.vendaze.com/v1/people?company_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890&order_by=full_name&order=asc&page=2&per_page=25" \
  -H "Authorization: Bearer {access_token}"

Erros de validação

Filtros com valores inválidos retornam 422 identificando o campo:

{
  "error": {
    "code": "validation_error",
    "message": "Validation failed.",
    "fields": {
      "company_id": "Must be a valid UUID.",
      "created_after": "Must be a valid ISO 8601 date."
    },
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Visão Geral

Começando

Utilizando a API

Boas Práticas

Filtros por recurso

`GET /v1/people`

`GET /v1/companies`

`GET /v1/deals`

`GET /v1/pipelines`

`GET /v1/tasks`

`GET /v1/activities`

`GET /v1/products`

`GET /v1/tags`

`GET /v1/lists`

`GET /v1/task-types`

`GET /v1/custom-fields`

Combinando filtros com paginação

Erros de validação

​Filtros por recurso

​GET /v1/people

​GET /v1/companies

​GET /v1/deals

​GET /v1/pipelines

​GET /v1/tasks

​GET /v1/activities

​GET /v1/products

​GET /v1/tags

​GET /v1/lists

​GET /v1/task-types

​GET /v1/custom-fields

​Combinando filtros com paginação

​Erros de validação

Filtros por recurso

`GET /v1/people`

`GET /v1/companies`

`GET /v1/deals`

`GET /v1/pipelines`

`GET /v1/tasks`

`GET /v1/activities`

`GET /v1/products`

`GET /v1/tags`

`GET /v1/lists`

`GET /v1/task-types`

`GET /v1/custom-fields`

Combinando filtros com paginação

Erros de validação