Conversa Labs Help Center
en
Language
pt_BR Portuguese (Brazil) en English es Spanish

Contact fiscal data and address (tax ID, billing)

Open in
View as Markdown Open in ChatGPT Open in Claude
Conversa Labs

Conversa Labs

Last updated on Jul 27, 2026

Overview

Every contact natively stores its fiscal identity — legal type (Individual or Business), tax ID (CPF/CNPJ) and tax country — plus the full postal address (ZIP, street, number, complement, neighborhood, city, state and country). Optionally, a billing address different from the principal one.

This data automatically feeds the modules that need it: Payments prefills the payer (document and address) when creating charges and subscriptions, message templates and automations gain variables such as {{contact.address_city}}, and the account AI sees the address for context — The document is shown in full to your team in the panel and the form; it is masked only when an access role says so, for bots/integrations, and in external outputs (webhooks, CSV export and message variables).

Prerequisites

  • Permission to edit contacts.
  • For automatic charge prefill: an active gateway connection in Payments.

Step by step

  1. Open the contact (Contacts page or conversation panel) and click Edit.
  2. Fill in the Type (Individual or Business), the Tax ID and the tax country (e.g. BR). A saved document is prefilled with its real value: edit it to correct it, or clear the field to remove it.
  3. In the Address section, enter the ZIP (CEP): street, neighborhood, city and state are autofilled for Brazilian codes. Complete number and complement.
  4. If billing goes to another address, check Different billing address. Use the Copy from address button to bring everything over in one click and tweak only what changes.
  5. Save. From then on, charges and subscriptions created for this contact come with the document and address prefilled.

Settings & options

  • Document visibility: the tax ID is validated on save (check digits) and is visible to your team. To hide it from part of the team, use Roles & access and set the tax_id field rule to masked (shows ***.***.***-09) or hidden. The value is always stored encrypted.
  • Billing address: unchecking the option makes billing use the principal address again.
  • CSV import: the columns legal_type, tax_id, tax_country, address_zip, address_street, address_number, address_complement, address_neighborhood, address_city, address_state and address_country fill the native fields.
  • Export: the document always exports masked; the address exports as flattened address_* columns.
  • Variables: {{contact.masked_tax_id}}, {{contact.legal_type}}, {{contact.tax_country}} and {{contact.address_zip}} … {{contact.address_country}} work in canned responses, macros, automations, follow-ups and the FlowBuilder.

Use cases

  • Issue a Mercado Pago boleto without asking for the address again: the contact already has it.
  • A business with a head office (principal) billed at another unit (billing address).
  • Segment by city/country — the address feeds the contact location filters.
  • Segment by legal type (individual/business), document type, fiscal country and address (ZIP, city, state, country) in the advanced contact filters and segments.
  • Automate: the "Set contact field (fiscal/address)" action in automations, macros and flows writes legal type, document and address straight onto the native fields — e.g. a flow that asks for the CPF/CNPJ and saves the reply on the contact.
  • Condition: contact-triggered automations can gate on legal type, document type, fiscal country and address; in flows, the condition node uses the same contact variables.

Tips, limits & best practices

  • Brazilian documents are check-digit validated; an invalid document is not stored in the native field (the charge can still be created with the typed value — the gateway decides).
  • Accounts that used the payment custom attributes (payment_document, payment_address_*) lose nothing: those values keep being read as a fallback until the automatic migration, and charges now write only to the native fields.
  • The ZIP autofill covers Brazilian addresses; for other countries, fill in manually.

Troubleshooting

  • "The tax ID was not saved": check the digits — documents with an invalid check digit are rejected to protect billing.
  • The charge asks for a document even though the contact has one: confirm the document shows filled in on the contact panel; if empty, save it again.
  • The ZIP did not autofill the address: the CEP service may be unavailable — fill in manually; nothing is overwritten.

See also