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.

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.

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 (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:

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:

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

See Virtual Card Error Codes for the full list.

Related pages

• Add Virtual Card Address
• Create Virtual Card
• Add Funding Sources
• User KYC Verification
• Business registration
• Test Addresses

Want to learn more? Contact us at [email protected]. Speak with our experts for more info or to request a demo.