> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluz.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Address Formatting Requirements

Addresses are submitted in several places across the Fluz API — user identity verification (KYC), business registration (KYB), funding sources, and virtual card issuance. This page defines how to format address fields so they are accepted, and the additional validation that applies specifically to card issuance.

<Tip>
  **Where this applies**

  Address fields use the same structure across the API. The **formatting rules** below apply everywhere. The **card issuance requirements** (US-only, no PO boxes, Smarty validation) apply only where noted.
</Tip>

## Address fields

Every address object uses the same structured fields. Depending on the call, the object may be named `billingAddress`, `businessLegalAddress`, or an owner/individual address, but the field names are consistent.

| Field                | Required | Format                                                                                                         |
| -------------------- | -------- | -------------------------------------------------------------------------------------------------------------- |
| `streetAddressLine1` | Yes      | Primary street address (building number + street). Must be a real, deliverable street address.                 |
| `streetAddressLine2` | No       | Apartment, suite, unit, or floor. Use a standard secondary designator (`Apt`, `Ste`, `Unit`, `Rm`, `Fl`, `#`). |
| `city`               | Yes      | City name. Must be the city USPS associates with the ZIP code.                                                 |
| `state`              | Yes      | Two-letter US state code (e.g. `NY`) or full state name.                                                       |
| `postalCode`         | Yes      | 5-digit US ZIP code. Must belong to the city and state provided.                                               |
| `country`            | Yes      | Country name. Constraints vary by context — see [Country by context](#country-by-context).                     |

## Formatting rules

These apply to **every** address you submit, in any section of the API:

1. **Use the structured fields.** Put the street on `streetAddressLine1` and the unit on `streetAddressLine2` — don't combine everything into one line.
2. **Use a real, deliverable address.** The building number must exist on the named street. A real street is not enough — `500 Main St` is invalid if the highest number on Main St is `480`.
3. **Keep city, state, and ZIP consistent.** The ZIP code must be the one assigned to that city and state. A mismatched ZIP is the most common cause of a rejected address.
4. **Use USPS abbreviations.** Standard suffixes (`St`, `Ave`, `Blvd`, `Dr`, `Ln`, `Rd`, `Ct`, `Pkwy`) and directionals (`N`, `S`, `E`, `W`, `NE`, `NW`, `SE`, `SW`) match most reliably.
5. **Put unit / apartment / suite in** `streetAddressLine2` using a recognized designator. If USPS requires a secondary unit for a building and none is provided, the address can fail to validate.
6. **Send a 5-digit ZIP** for US addresses. ZIP+4 is added automatically during standardization.

## Additional requirements for card issuance

Virtual card billing addresses are validated and standardized through [Smarty](https://www.smarty.com/) (USPS Delivery Point Validation) before they are saved. This applies to [Add Virtual Card Address](/features/add-billing-address), [Create Virtual Card](/features/create-card), and [card issuance for authorized users](/features/create-virtual-card-for-authorized-user).

* **US addresses only.** Set `country` to `United States`.
* **No PO boxes.** The card issuer does not accept PO box addresses, even if USPS considers them deliverable.
* **Must be Smarty-verified.** If the address cannot be matched to a real, deliverable US delivery point, the request is rejected with `VC-0025` and **no address is saved**. Retrying with the same values will fail again — the address itself must change.

Bank card billing addresses ([Add Funding Sources](/features/add-bank-card)) share the same field structure and should match the address on file with the card issuer. A mismatched billing address can cause the card to be declined during the address verification (AVS) check.

## Country by context

Not every address is US-only. Use the right constraint for the call you are making:

| Context                                            | Country constraint                                                                                                    |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Virtual card billing address                       | US only (`United States`).                                                                                            |
| Bank card billing address                          | Should match the card issuer's records (typically US).                                                                |
| Business registration (KYB) `businessLegalAddress` | International addresses accepted (country name, ISO 3166). Some countries are restricted for KYB (e.g. Russia, Iran). |
| User KYC verification                              | The user's residential address.                                                                                       |

## Why an address is rejected (`VC-0025`)

For card issuance, an address fails when Smarty cannot confirm it as a deliverable US delivery point. The most common reasons:

| Reason                           | What it means                                                                            |
| -------------------------------- | ---------------------------------------------------------------------------------------- |
| City / State / ZIP mismatch      | The ZIP code does not belong to the city or state provided.                              |
| Invalid building number          | The street exists, but the primary (building) number does not exist on it.               |
| Address not found                | The street or address is not present in USPS data.                                       |
| Missing / invalid secondary unit | USPS requires an apartment or suite number for this building and it is missing or wrong. |
| Non-deliverable point            | The address maps to a vacant or otherwise undeliverable delivery point.                  |
| PO box or non-US address         | Rejected by the card issuer (PO boxes) or unsupported (outside the US).                  |

## Worked examples

### Example 1 — City / ZIP mismatch

```text theme={null}
2581 Oakwood Avenue, New York, NY 10605
```

**Rejected (**`VC-0025`**).** ZIP code `10605` belongs to **White Plains, NY** (Westchester County), not New York City — so the city and ZIP do not match. In addition, `2581 Oakwood Avenue` is not a confirmed delivery point in that ZIP. Smarty returns no valid match, so the address is not saved.

**Fix:** submit the ZIP that USPS assigns to the city (or the city that matches the ZIP), and a building number that exists on the street.

### Example 2 — Invalid building number

```text theme={null}
896 S State St, Dover, DE 19904
```

**Rejected (**`VC-0025`**).** `S State St` exists in Dover, DE, but `896` is not a confirmed USPS delivery point for that street and ZIP. Because the specific building number cannot be validated, Smarty returns no deliverable match.

**Fix:** confirm the exact building number and the ZIP that covers that block of the street.

### A valid submission

```json theme={null}
{
  "billingAddress": {
    "streetAddressLine1": "1600 Amphitheatre Pkwy",
    "streetAddressLine2": "",
    "country": "United States",
    "city": "Mountain View",
    "state": "CA",
    "postalCode": "94043"
  }
}
```

Saved and normalized (city, state, and postal code stored in uppercase; ZIP+4 added):

```json theme={null}
{
  "streetAddressLine1": "1600 Amphitheatre Pkwy",
  "streetAddressLine2": null,
  "country": "United States",
  "city": "MOUNTAIN VIEW",
  "state": "CA",
  "postalCode": "94043"
}
```

## Handling `VC-0025` in your integration

* **Collect the address in structured fields** rather than a single free-text field, so you can prompt for the specific part that needs fixing.
* **Do not blind-retry.** The same address will keep returning `VC-0025`. Surface the error and ask the user to correct the address.
* **Validate before you submit (optional).** Running an address autocomplete or verification step in your own UI reduces failed round-trips.
* **Nothing is saved on failure**, so there is no cleanup before retrying with corrected values.

## Error reference

| Error                     | Code      | Message                                                                                                      |
| ------------------------- | --------- | ------------------------------------------------------------------------------------------------------------ |
| `INVALID_BILLING_ADDRESS` | `VC-0025` | The billing address could not be verified. Please check the street, city, state, and ZIP code and try again. |

See [Virtual Card Error Codes](/features/virtual-card-error-codes) for the full list.

## Next steps

<CardGroup cols={2}>
  <Card title="Test addresses" icon="flask-conical" href="/test-addresses">
    Known-good and known-bad addresses for exercising every validation outcome in staging.
  </Card>

  <Card title="General API error codes" icon="triangle-alert" href="/get-started/general-api-error-codes">
    Where address errors fit in the broader error code namespace.
  </Card>
</CardGroup>

***

**Want to learn more?** Contact us at [partnerships@fluz.app](mailto:partnerships@fluz.app). Speak with our experts for more info or to request a demo.