Addresses in Brazil

Addresses in the API follow the Brazilian postal format used by Correios, the national postal service. You only need to send three fields: the recipient’s name, the postal code and the building number. CartaFlow fills in the rest from the postal code.

How a Brazilian address is writtenCopy Anchor Link

If you are new to Brazilian addresses, these are the parts, in the order they appear on an envelope:

Destinatário Exemplo              <- name
Rua Exemplo, 128, Ap. 52          <- street, number, complement
Centro                            <- neighborhood (bairro)
01001-000 São Paulo/SP            <- postal code (CEP), city, state (UF)

• CEP is the postal code: 8 digits, usually written 00000-000. A CEP often identifies a single street, or one side of it, so it tells you the street, neighborhood, city and state.
• Bairro is the neighborhood. Every urban address has one, and Correios uses it for sorting.
• UF is the two-letter code of the state, such as SP for São Paulo.
• Number goes after the street name. Addresses without a number use S/N ("sem número").
• Complement is the apartment, block, suite or floor.

The address ruleCopy Anchor Link

• Required: name, postal_code and number.
• Fields you send are used as you sent them. CartaFlow does not replace your neighborhood or street with the one in the postal code database.
• Fields you leave out are filled in from the postal code: street, neighborhood, city and state.
• If a field is missing and the postal code does not provide it, the API answers 422 with the code address_incomplete, and nothing is created or charged. This happens with postal codes that cover a whole city, common in small towns, which have no street or neighborhood.

The same rule applies to a letter’s recipient and sender (to and from) and to the address of a verification.

The shortest addressCopy Anchor Link

"to": {
  "name": "Destinatário Exemplo",
  "postal_code": "01001-000",
  "number": "128",
  "complement": "Ap. 52"
}

The letter comes back with the complete address, as it will be printed:

"to": {
  "name": "Destinatário Exemplo",
  "street": "Praça da Sé",
  "number": "128",
  "complement": "Ap. 52",
  "neighborhood": "Sé",
  "city": "São Paulo",
  "state": "SP",
  "postal_code": "01001-000"
}

Part of the address from you, part from the postal codeCopy Anchor Link

If your records have the neighborhood as the customer wrote it, send it. CartaFlow uses your neighborhood and looks up only what is missing.

"to": {
  "name": "Destinatário Exemplo",
  "postal_code": "01001-000",
  "number": "128",
  "neighborhood": "Centro"
}

"to": {
  "name": "Destinatário Exemplo",
  "street": "Praça da Sé",
  "number": "128",
  "complement": null,
  "neighborhood": "Centro",
  "city": "São Paulo",
  "state": "SP",
  "postal_code": "01001-000"
}

The street, city and state came from the postal code. The neighborhood is the one you sent.

The complete addressCopy Anchor Link

When you already have every field, send them all. Nothing is looked up.

"to": {
  "name": "Destinatário Exemplo",
  "street": "Rua Exemplo",
  "number": "128",
  "complement": "Ap. 52",
  "neighborhood": "Centro",
  "city": "São Paulo",
  "state": "SP",
  "postal_code": "01001-000"
}

The fieldsCopy Anchor Link

In responses every field is always present. complement is null when the address has none.

State codes (UF)Copy Anchor Link

Fill in your customer’s form from the postal codeCopy Anchor Link

GET /v1/postal-codes/{postal_code} returns the street, neighborhood, city and state of a postal code. It is the same lookup the API uses to complete addresses. Free of charge.

curl "https://api.cartaflow.com.br/v1/postal-codes/01001-000" \
  -H "Authorization: Bearer $CARTAFLOW_API_KEY"

{
  "object": "postal_code",
  "postal_code": "01001-000",
  "street": "Praça da Sé",
  "neighborhood": "Sé",
  "city": "São Paulo",
  "state": "SP"
}

street and neighborhood are null when the postal code covers a whole city. In that case, ask your customer for the street and neighborhood and send both with the letter.

SenderCopy Anchor Link

The sender is printed on one line above the recipient. Correios returns the letter to this address when it cannot be delivered.

• Send from with the letter to use a specific sender, with the same field rules as the recipient.
• If you leave out from, we use the account’s default sender, which you set in the dashboard under Configurações > Empresa (Settings > Company). It shows as default_sender in GET /v1/account.

Addresses in Brazil onlyCopy Anchor Link

CartaFlow prints and posts in Brazil, to addresses in Brazil. That is why there is no country field and the postal code is always required.

Address errorsCopy Anchor Link

Address problems come back as a 422 validation_error, with one item in details per field. param names the field, for example to.postal_code or from.street.

{
  "error": {
    "type": "validation_error",
    "code": "invalid_parameters",
    "message": "One field has a problem. See details.",
    "request_id": "req_9Vb4Xk2Lq8Mz",
    "doc_url": "https://docs.cartaflow.com.br/en/errors#invalid_parameters",
    "details": [
      {
        "param": "to.street",
        "code": "address_incomplete",
        "message": "Postal code 13165-000 covers the whole city and has no street. Send street and neighborhood."
      }
    ]
  }
}

The full list of codes is in Errors.