Structured addresses

Vitesse uses a structured postal address model aligned to ISO 20022.

Use this format wherever a postal address is required, for example for recipient mailing addresses.

Address structure rules

For street information, provide either:

StreetName and BuildingNumber, or
Up to two AddressLines: Line 1 (and optionally Line2), when structured street fields are not available
For example:
```
AddressLines: [
  "Suite 46",  
  "Floor 5"  
]
```

If you provide StreetName and BuildingNumber,you can also use address lines for additional details such as floor, unit, building name, or department.

📘
You must provide the mandatory fields listed below, whether you use structured street fields or address lines.

Structured address fields

For APIs, use the API field column.
For batch files, use the CSV header column.

If you need to provide a postal (mailing) address in a batch file, replace the RecipientAddress prefix with PostalRecipientAddress.

For example:

RecipientAddressStreetName
PostalRecipientAddressStreetName

📘
Fields marked with * are mandatory. Bracketed asterisks (*) are for mandatory parameters with exceptions.

API field	CSV header	Datatype	Definition	Example
`StreetName`	RecipientAddressStreetName	String (max chars 128)	The street name. Provide this field together with `BuildingNumber` unless you are using address lines instead.	Main Street
`BuildingNumber`	RecipientAddressBuildingNumber		The building or street number. Provide this field together with `StreetName` unless you are using address lines instead.	742
`TownName`*	RecipientAddressTownName*		The city or town.	Springfield
`PostCode`*	RecipientAddressPostCode*		The postal or ZIP code (maximum 10 characters).	62704
`CountrySubDivision`*	RecipientAddressCountrySubDivision*		The two-character US state code.	IL
`Country`*	RecipientAddressCountry*		The two-character ISO 3166-1 alpha-2 country code. For cheques, you must use `US`.	US
`AddressLines [ ]` See Address structure above.	RecipientAddressLine1		Additional address detail (for example, floor, unit, building name, or department), or the street alternative when structured street fields are not provided.	Suite 46
	RecipientAddressLine2		Optional additional complimentary address detail. Do not provide this field when `StreetName` and `BuildingNumber` are supplied.	Floor 5

Additional fields for postal recipient addresses

When an address is used for mailing (for example, printing on an envelope), you must provide an addressee.

📘
Provide either Name or CompanyName, not both.

Header	Description	Example
`Name`	The For Attention Of name printed on the envelope.	Michael Thompson
`CompanyName`	The company name to print on the envelope.	Vitesse PSP Limited

Deprecated legacy address fields

Do not use the following legacy fields in your batches:

Legacy field	Use instead
`RecipientAddressCompanyName`	`PostalRecipientAddressCompanyName`
`RecipientAddressForAttentionOf`	`PostalRecipientAddressName`
`RecipientAddressLine3`	An appropriate ISO 20022 structured address field

We continue to support these legacy fields for backward compatibility, but we may remove them in a future release.