🎉 Celebrate with 10% OFF on All Products! Use Code: GFEX10 Or Buy Any 2+ Items for 30% OFF with Code: GFEX30!

Gravity Forms Brazil CEP Autofill Premium Add-on Setup Guide

Updated 9 min read Gravity Forms Integrations A–Z
On this page
  1. Video walkthrough
  2. Requirements
  3. Installation
  4. The Brazil address type
  5. How the autofill works
  6. When something goes wrong
  7. Data sources, cache and limits
  8. CPF and CNPJ
  9. Entries, exports and merge tags
  10. Forms with several address fields, pages and AJAX
  11. Translation
  12. Without a licence
  13. Frequently asked questions
  14. Does the visitor’s browser talk to ViaCEP or BrasilAPI?
  15. What if a CEP is new and the services do not know it?
  16. Will it work with Save and Continue and notifications?
  17. Can I use it for the “copy values from another field” option?

Video walkthrough

Gravity Forms Brazil CEP Autofill: Fill the Address from the CEP, Validate CPF and CNPJ
Watch: fill a Brazilian address from the CEP and check CPF and CNPJ in Gravity Forms, step by step. Watch on YouTube

The Gravity Forms Brazil CEP Autofill Premium Add-on adds a Brazilian address type to the Gravity Forms Address field. The visitor types the CEP, and the logradouro (street), bairro (neighbourhood), cidade (city) and UF (state) fill in by themselves. The rest of the form follows Brazilian habits: the CEP comes first, número and complemento have their own boxes, the UF is a list of the 27 units, the CEP is written 00000-000, and entries and merge tags print the address the way it is written on an envelope.

The lookup is made by your own server, never by the visitor’s browser, through a small WordPress REST route with a nonce, a rate limit and a cache. Two free services without a key can answer: ViaCEP and BrasilAPI. If one is down, the other is asked. If both are down, the visitor types the address and the form is sent as usual.

A Gravity Forms order form with the Brazil address type: the CEP 01310-200 was typed, and Logradouro, Bairro, Cidade and UF were filled in with Avenida Paulista, Bela Vista, São Paulo and SP, with a green message under the CEP and the cursor waiting in the Número field
Type the CEP and the address fills itself in. The cursor waits in Número, and every field can still be edited.

Requirements

  • WordPress 6.5 or newer and PHP 7.4 or newer (tested up to PHP 8.3).
  • Gravity Forms 2.9 or newer (tested with 2.9.8 and 3.1.2).
  • A server that can make outgoing HTTPS requests to viacep.com.br or brasilapi.com.br. No account, no key.

Installation

  1. Download the zip from your GravityExtra account and upload it in Plugins, Add New, Upload Plugin.
  2. Activate the plugin. Gravity Forms must be active.
  3. Go to Forms, Settings, Brazil CEP and activate your licence key.
  4. Open a form, add an Address field and choose Brazil (CEP) as the Address Type.
  5. Open the form on your site, type a CEP and watch the address fill in.
The add-on settings in Forms, Settings, Brazil CEP: the licence box, the choice of data source between ViaCEP and BrasilAPI, how long answers are kept, the lookups per visitor and minute, and the mask and focus options
One settings page for the data source, the cache, the rate limit and the behaviour of the form.

The Brazil address type

In the form editor, select an Address field and open the Address Type list. Next to International, United States and Canadian you now find Brazil (CEP). The field then shows these inputs, in this order:

Order Input Notes
1 CEP Mask 00000-000, numeric keyboard on phones, 8 digits.
2 Logradouro Street, avenue, square. Filled from the CEP.
3 Número Typed by the visitor. Required when the field is required (s/n is accepted).
4 Complemento Apartment, block, suite. Optional.
5 Bairro Neighbourhood. Filled from the CEP.
6 Cidade City. Filled from the CEP.
7 UF A list of the 27 federative units. Filled from the CEP.
8 País Brasil, stored without being shown.

The labels are in Brazilian Portuguese on every site, because a Brazilian form should read as one even on a site whose admin is in English. If you prefer other words, use the custom sub-labels of the Address field in the editor: they win over ours. A developer can also change them all at once with the gfxbrcep_labels filter.

Gravity Forms has no input for número and bairro, so the add-on adds two inputs to the field (the input numbers .7 and .8). They are saved with the entry, exported in the CSV, available as merge tags and shown on the entry page, like every other input of the field. The inputs are kept in the form; if you later change the address type back to International, they are hidden but the saved values stay in your entries.

How the autofill works

  1. The visitor types the CEP. The add-on formats it as 00000-000 while they type.
  2. When the 8th digit is typed, the script asks your server for that CEP. A short Buscando o endereço message appears under the field.
  3. Your server answers from its cache, or asks ViaCEP, or BrasilAPI. Only the 8 digits of the CEP leave your server.
  4. The street, neighbourhood, city and UF are filled in. The message becomes Endereço preenchido, and the cursor moves to Número (or to Logradouro, when the CEP has no street, as happens for a small town that has a single CEP).
  5. The visitor types the número and, if needed, the complemento. Every field stays editable: if the street is spelt differently on the visitor’s door, they can change it.

Typing another CEP replaces the filled values; shortening the CEP clears the message. Número and complemento are never touched by the lookup. The lookup never runs at submit time and never stops a form from being sent.

When something goes wrong

What happened What the visitor sees What happens next
The CEP does not exist CEP não encontrado. Confira o número ou preencha o endereço manualmente. Nothing is filled. The visitor types the address.
Both services are offline, too slow or the visitor made too many lookups Não foi possível consultar o CEP agora. Preencha o endereço manualmente. Nothing is filled. The form can be sent.
The CEP has fewer than 8 digits when the visitor leaves the field Informe um CEP com 8 números (00000-000). No lookup is made.
The CEP is wrong when the form is sent Informe um CEP válido, com 8 números (00000-000). The form is shown again with the values kept.

Every message can be changed with the gfxbrcep_strings filter.

Data sources, cache and limits

Open Forms, Settings, Brazil CEP to choose the data source:

  • ViaCEP first (the default): ViaCEP, at viacep.com.br, is asked first. BrasilAPI answers when ViaCEP is down, too slow, or does not know the CEP.
  • BrasilAPI first: the other way round. BrasilAPI, at brasilapi.com.br, is an open source project that gathers several CEP sources.
  • ViaCEP only or BrasilAPI only: no fallback.

Both services are free and need no key. Read their pages before you go live: ViaCEP explains its endpoint and warns that massive use can be blocked, and the BrasilAPI documentation asks users to keep the volume of requests close to that of real visitors. That is the reason for the three protections below.

Protection What it does Default
Nonce The route answers only to a request that carries a nonce printed on your page. A page kept by a cache for a day carries an old nonce, so the script asks for a fresh one once and tries again. Always on
Rate limit Each visitor (counted by the connecting IP address) can make a limited number of lookups per minute. Past the limit the route answers 429 and the visitor sees the offline message. 20 per minute
Cache A found CEP is kept in WordPress transients, a CEP that was not found for one day. The same CEP typed by a thousand visitors is one call. 30 days (0 to 365; 0 switches it off)

A service that failed is skipped for one minute, so a service that is down does not slow down every visitor. Calls have a 5 second limit, verify the certificate of the service and accept only a small answer. Whatever the service answers, only five cleaned fields (CEP, street, neighbourhood, city, UF) are sent to the browser, and the UF must be one of the 27 real ones.

Behind a proxy or a CDN

The rate limit counts the address your server sees. If every visitor looks like the same address, set the real address on the server (the usual way for your host) or return it from the gfxbrcep_client_ip filter, and use the gfxbrcep_rate_limit filter to change the limit.

CPF and CNPJ

Single Line Text fields have a new option on the Advanced tab: CPF or CNPJ validation. With it:

  • The CPF (11 digits) or the CNPJ (14 characters) is formatted while typing: 000.000.000-00 and 00.000.000/0000-00.
  • The number of characters and the two check digits are verified when the form is sent, and a wrong number gets a clear message. An empty field is left to the Required setting.
  • The new alphanumeric CNPJ, which the Receita Federal introduces in 2026 (letters and digits in the first 12 positions, two numeric check digits), is accepted.
  • The value is saved with the usual marks, so all your entries look the same.

What the check does not do

It checks the format and the check digits. It cannot tell you that a number is registered, active or belongs to the person who typed it. Do not use it as proof of identity.

Entries, exports and merge tags

The entry detail page, the {all_fields} merge tag and the merge tag of the whole field print the Brazilian address:

Avenida Paulista, 1578 - Conjunto 12
Bela Vista
São Paulo - SP
CEP 01310-200
Brasil
Merge tag Result
{Endereço:5} The address on five lines (a text e-mail) or joined with line breaks (HTML), with a map link on the entry page.
{Endereço:5:one_line} Avenida Paulista, 1578 – Conjunto 12, Bela Vista, São Paulo – SP, CEP 01310-200, Brasil
{Endereço:5.1} Logradouro only (the input numbers are .1 logradouro, .2 complemento, .3 cidade, .4 UF, .5 CEP, .6 país, .7 número, .8 bairro).
{Endereço:5.7} Número only.

In the CSV export, each input has its own column with a Portuguese header, so you can sort and filter by UF, cidade or CEP in a spreadsheet. The saved CEP always has the form 00000-000.

The Gravity Forms entry detail page in the WordPress admin showing the Brazilian address printed as Avenida Paulista, 1578 - Conjunto 12, Bela Vista, São Paulo - SP, CEP 01310-200 and Brasil
The entry prints the address the Brazilian way, and número and bairro are saved as separate inputs.

Forms with several address fields, pages and AJAX

  • You can have several Brazil address fields in one form (billing and delivery, for example). Each one has its own lookup and its own message.
  • In a multi-page form the lookup works on any page, and the values stay when the visitor goes back and forward.
  • AJAX forms work: after a validation error the form is shown again and the lookup keeps working.
  • To switch the lookup off for one field and keep the Brazilian layout, untick Fill the address from the CEP on the Advanced tab of the field.

Translation

The settings pages and the editor options come with a Brazilian Portuguese (pt_BR) translation that is used when the WordPress language is Portuguese (Brazil). The words the visitor sees on the form are Portuguese on every site, as explained above.

Without a licence

If the licence lapses, the Brazil address type keeps rendering and saving the address, so your forms and entries are safe. The lookup, the masks, the validators and the Brazilian format of merge tags switch off until the licence is active again.

Frequently asked questions

Does the visitor’s browser talk to ViaCEP or BrasilAPI?

No. The browser asks your own WordPress site, and your server asks the service. Nothing but the 8 digits of the CEP leaves your server.

What if a CEP is new and the services do not know it?

The visitor sees the not found message and types the address. Choose ViaCEP first or BrasilAPI first according to which one knows your region better; with the default both are asked before the not found message appears.

Will it work with Save and Continue and notifications?

Yes. The values are saved like any other input of the Address field, and notifications use the merge tags above.

Can I use it for the “copy values from another field” option?

The Gravity Forms copy option copies the six standard inputs. Número and bairro are not copied, so the visitor types them again.

Install it, choose Brazil (CEP) in your Address fields and your Brazilian customers will type a CEP, a número and nothing else.

Let your Brazilian customers type a CEP instead of a whole address

See the Brazil CEP Autofill add-on

Still need help?

Our support team answers tickets every day, usually within a few hours.

0
0
Your Cart
Your cart is emptyReturn to Shop
🔥 FREQUENTLY BOUGHT TOGETHER
Complete Combo & Save 40%!
ITEM IN YOUR CART
Gravity Forms Klaviyo Add-on
$39.00/yr
+
🎁 RECOMMENDED ADD-ON SAVE 40% OFF
Original Price: $39.00/yr
Bundle Special Price: $23.40/yr