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.

Where this appliesAddress 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.

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.

Formatting rules

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

Use the structured fields. Put the street on streetAddressLine1 and the unit on streetAddressLine2 — don’t combine everything into one line.
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.
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.
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.
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.
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 (USPS Delivery Point Validation) before they are saved. This applies to Add Virtual Card Address, Create Virtual Card, and card issuance for authorized users.

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) 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

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

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

{
  "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):

{
  "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 for the full list.

Next steps

Test addresses

Known-good and known-bad addresses for exercising every validation outcome in staging.

General API error codes

Where address errors fit in the broader error code namespace.

Want to learn more? Contact us at partnerships@fluz.app. Speak with our experts for more info or to request a demo.

Developers

Recipes

Address Formatting Requirements

Address fields

Formatting rules

Additional requirements for card issuance

Country by context

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

Worked examples

Example 1 — City / ZIP mismatch

Example 2 — Invalid building number

A valid submission

Handling `VC-0025` in your integration

Error reference

Next steps

Test addresses

General API error codes

​Address fields

​Formatting rules

​Additional requirements for card issuance

​Country by context

​Why an address is rejected (VC-0025)

​Worked examples

​Example 1 — City / ZIP mismatch

​Example 2 — Invalid building number

​A valid submission

​Handling VC-0025 in your integration

​Error reference

​Next steps

Test addresses

General API error codes

Address fields

Formatting rules

Additional requirements for card issuance

Country by context

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

Worked examples

Example 1 — City / ZIP mismatch

Example 2 — Invalid building number

A valid submission

Handling `VC-0025` in your integration

Error reference

Next steps