Search Contacts

General free-text search across indexed contact fields. Use it for a broad query or a public contact code. When the user provides a known name, email, phone, CPF, or CNPJ, prefer the corresponding dedicated field.

Partial or complete name of a person or organization, matched without case or diacritic sensitivity. Use this field whenever a name is the search criterion. If an exact search returns no records and this is the only identifier, the tool may return similar names. Examples: 'Tiago', 'Maria Silva', 'Construtora ABC'.

Exact contact email, matched case-insensitively.

Contact phone with or without punctuation, area code, and country code. Formatting is ignored and the value must contain at least eight digits.

Contact CPF or CNPJ with or without formatting.

Filter by entity type. Use 'person' for individuals, 'organization' for companies, or 'all' to include people, organizations, and leads. Without this field, the normal contact search excludes leads.

Filter by activation status. Use 'active', 'inactive', or 'all'. Defaults to 'active'.

Set to true to return only leads; this takes precedence over contact_type. Leave it unset for a normal contact search, which excludes leads by default.

Comma-separated tags used to filter contacts. Multiple tags are matched with OR semantics. Example: 'client,vip'.

Name or partial name of the manager responsible for the contact. The lookup is case-insensitive and must resolve to one active user; otherwise the tool returns options for disambiguation. When the user asks for their own contacts, leave this field empty and set requesting_user_only=true. Examples: 'Maria', 'Carlos Souza'.

Exact email of the manager responsible for the contact. Prefer this over manager_name when available because it avoids name ambiguity.

Predefined contact filter. Use: 'shared_with_me' or 'shared_with_others' for sharing; 'without_manager', 'without_email', or 'without_phone' for missing data; 'with_deal' or 'without_deal' for deal linkage; 'favorites' for favorites; 'pending' for pending review; 'out_of_date' for contacts not updated in 365 days; 'out_of_date_90_days' for 90 days; 'new_contacts' for contacts created in the last 30 days; 'birthdays_all' or 'birthdays_only_mine' for today's birthdays; and 'my_contacts' for contacts owned by the requesting user.

Set to true when the user refers to their own contacts using phrases such as 'meus contatos', 'meus clientes', 'meus leads', or 'contatos que eu tenho'. When smart_list is omitted, this applies smart_list='my_contacts'. Do not set it when the user asks about another manager's contacts.

Filter by contact creation date. Allowed values: 'today', 'this_week', 'this_month', 'last_month', 'last_three_months', 'current_year', and 'last_year'. Example: 'contatos criados esta semana' → create_period='this_week'.

Opaque pagination cursor. Send it only when a cursor was supplied by external context; do not invent one or send it on the first request. The current MCP tool response does not expose the next cursor.