Learn about addresses in Numeral
Address structure
Addresses are used for originating accounts and receiving accounts in payment orders and incoming payments. They include the following attributes.
| Attribute | Description |
|---|---|
| building_number string | Building / street number of the originating/receiving party. |
| street_name string | Street name of the originating/receiving party. |
| postal_code string | Postal / zip code of the originating/receiving party. |
| region_state string | Region or state of the originating/receiving party. |
| city string | City / town name of the originating/receiving party. |
| country string | ISO 3166 alpha-2 country code of the originating/receiving party. For instance: GB, FR, or US. |
| line_1 string | Line 1 (unstructured) of the originating/receiving party. |
| line_2 string | Line 2 (unstructured) of the originating/receiving party. |
| department string | Department of the originating/receiving party. Only supported for Incoming payments. |
| sub_department string | Sub-department of the originating/receiving party. Only supported for Incoming payments. |
| building_name string | Building name of the originating/receiving party's address. Only supported for Incoming payments. |
| floor string | Floor number of the originating/receiving party's address. Only supported for Incoming payments. |
| postal_box string | Post office box of the originating/receiving party. Only supported for Incoming payments. |
| room string | Room number of the originating/receiving party's address. Only supported for Incoming payments. |
| city_location_name string | Town location name of the originating/receiving party. Only supported for Incoming payments. |
| district_name string | District name of the originating/receiving party. Only supported for Incoming payments. |
Structured vs. unstructured address
Starting from November 23, 2025, the European Payments Council mandates that SEPA participants use structured addresses instead of unstructured addressed.
The key differences between unstructured addresses and structured addresses are the following.
Unstructured address
An unstructured address contains a country (usually in the form of an ISO-3166 country code) and up to two address lines.
In Numeral, it means using the country, and line_1 / line_2 properties. Address lines can contain anything relevant that identifies an address, hence the name "unstructured".
Structured address
A structured address must include a country and city as well as split street name and building number.
In Numeral, it means filling the country and city properties as well as optionally filling other properties like building_number, street_name, region_state, and postal_code, except the line_1 and line_2 unstructured properties.