> ## Documentation Index
> Fetch the complete documentation index at: https://developers.vendaze.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Listar pessoas
> Retorna uma lista paginada de pessoas no workspace.
`people:read`
## OpenAPI
````yaml /pt/api-reference/openapi.json get /v1/people
openapi: 3.1.0
info:
title: OAuth 2.1
description: Endpoints para registrar aplicativos e gerenciar tokens OAuth 2.1.
version: 1.0.0
contact:
name: Suporte Vendaze
email: suporte@vendaze.com
servers:
- url: https://api.vendaze.com
description: Produção
security:
- bearerAuth: []
tags:
- name: OAuth
- name: Pessoas
- name: Empresas
- name: Negócios
- name: Pipelines
- name: Tarefas
- name: Tipos de Tarefas
- name: Produtos
- name: Tags
- name: Listas
- name: Campos Adicionais
- name: Webhooks
paths:
/v1/people:
get:
tags:
- Pessoas
summary: Listar pessoas
description: |-
Retorna uma lista paginada de pessoas no workspace.
`people:read`
operationId: listPeople
parameters:
- name: page
in: query
schema:
type: integer
minimum: 1
default: 1
description: Número da página.
- name: per_page
in: query
schema:
type: integer
minimum: 1
maximum: 50
default: 50
description: 'Quantidade de registros por página. Máximo: 50.'
- name: order_by
in: query
schema:
type: string
enum:
- created_at
- updated_at
- full_name
default: created_at
description: Campo para ordenação.
- name: order
in: query
schema:
type: string
enum:
- asc
- desc
default: desc
description: Direção da ordenação.
- name: full_name
in: query
schema:
type: string
description: Filtrar por nome (contém, sem distinção de maiúsculas).
- name: email
in: query
schema:
type: string
format: email
description: >-
Filtrar por endereço de e-mail (match exato). Busca em todos os
e-mails do contato.
- name: company_id
in: query
schema:
type: string
format: uuid
description: >-
Filtrar por UUID de empresa. Retorna apenas pessoas vinculadas à
empresa informada.
- name: created_after
in: query
schema:
type: string
format: date-time
description: Retorna registros criados a partir desta data ISO 8601.
- name: created_before
in: query
schema:
type: string
format: date-time
description: Retorna registros criados até esta data ISO 8601.
- name: updated_after
in: query
schema:
type: string
format: date-time
description: Retorna registros atualizados a partir desta data ISO 8601.
- name: updated_before
in: query
schema:
type: string
format: date-time
description: Retorna registros atualizados até esta data ISO 8601.
responses:
'200':
description: Pessoas retornadas com sucesso.
content:
application/json:
schema:
$ref: '#/components/schemas/PeopleListResponse'
example:
data:
- id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
full_name: Maria Silva
emails:
- email: maria@empresa.com
type: work
phones:
- phone: '+5511999990001'
type: mobile
owner:
id: b2c3d4e5-f6a7-8901-bcde-f12345678901
email: joao@empresa.com
name: João Silva
avatar_url: null
entity_id: g7wwkh0
created_at: '2026-01-15T10:30:00Z'
updated_at: '2026-01-15T10:30:00Z'
custom_fields: []
meta:
total: 120
page: 1
per_page: 50
has_more: true
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/InsufficientScope'
'422':
$ref: '#/components/responses/ValidationError'
'429':
$ref: '#/components/responses/RateLimitExceeded'
'500':
$ref: '#/components/responses/InternalError'
components:
schemas:
PeopleListResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/PersonList'
meta:
$ref: '#/components/schemas/PaginationMeta'
PersonList:
type: object
description: Objeto compacto de pessoa retornado nas listagens.
properties:
id:
type: string
format: uuid
full_name:
type: string
maxLength: 70
example: Maria Silva
emails:
type: array
nullable: true
items:
$ref: '#/components/schemas/ContactEmail'
phones:
type: array
nullable: true
items:
$ref: '#/components/schemas/ContactPhone'
owner:
$ref: '#/components/schemas/Owner'
avatar_url:
type: string
format: uri
nullable: true
entity_id:
type: string
example: g7wwkh0
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
custom_fields:
type: array
items:
$ref: '#/components/schemas/CustomFieldValue'
PaginationMeta:
type: object
properties:
total:
type: integer
example: 1
page:
type: integer
example: 1
per_page:
type: integer
example: 50
has_more:
type: boolean
example: false
ErrorResponse:
type: object
properties:
error:
type: object
properties:
code:
type: string
message:
type: string
request_id:
type: string
format: uuid
ValidationErrorResponse:
type: object
properties:
error:
type: object
properties:
code:
type: string
example: validation_error
message:
type: string
example: Validation failed.
fields:
type: object
additionalProperties:
type: string
request_id:
type: string
format: uuid
ContactEmail:
type: object
required:
- email
properties:
email:
type: string
format: email
example: contato@acme.com
type:
type: string
enum:
- personal
- work
- other
description: Tipo do e-mail.
example: work
ContactPhone:
type: object
required:
- phone
properties:
phone:
type: string
example: '+551130000000'
type:
type: string
enum:
- mobile
- work
- residential
- other
description: Tipo do telefone.
example: work
Owner:
type: object
nullable: true
description: >-
Membro do workspace responsável pela tarefa. `null` quando nenhum
responsável está atribuído.
properties:
id:
type: string
format: uuid
name:
type: string
example: João Silva
email:
type: string
format: email
example: joao@empresa.com.br
CustomFieldValue:
type: object
properties:
id:
type: string
format: uuid
value: {}
field:
type: object
properties:
id:
type: string
format: uuid
label:
type: string
key:
type: string
type:
type: string
responses:
Unauthorized:
description: >-
Token ausente, inválido ou expirado. Códigos possíveis: `unauthorized`,
`token_expired`.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: unauthorized
message: Missing or invalid Authorization header.
request_id: 550e8400-e29b-41d4-a716-446655440000
InsufficientScope:
description: 'Token sem o escopo necessário. Código de erro: `insufficient_scope`.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: insufficient_scope
message: This endpoint requires the 'webhooks:read' scope.
request_id: 550e8400-e29b-41d4-a716-446655440000
ValidationError:
description: >-
Validação de entrada falhou. Código: `validation_error`. O objeto
`fields` mapeia cada campo inválido para uma descrição do problema.
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorResponse'
example:
error:
code: validation_error
message: Validation failed.
fields:
url: url must use HTTPS.
events: At least one event is required.
request_id: 550e8400-e29b-41d4-a716-446655440000
RateLimitExceeded:
description: 'Rate limit excedido. Código: `rate_limit_exceeded`.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: rate_limit_exceeded
message: Rate limit exceeded. Try again in 60 seconds.
request_id: 550e8400-e29b-41d4-a716-446655440000
InternalError:
description: 'Erro interno inesperado. Código: `internal_error`.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: internal_error
message: An unexpected error occurred.
request_id: 550e8400-e29b-41d4-a716-446655440000
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Access token OAuth 2.1.
````