Address API - Reference
Overview
Ingrid provides HTTP endpoints returning data in JSON format. We provide you with two environments:
- Stage - is our staging and testing environment where you do all the testing and developing against
- https://api-stage.ingrid.com
- Base url for Address API: https://api-stage.ingrid.com/address/v1
- Swagger UI
- Swagger JSON
- Production - is the production environment that you switch to when it’s time to go live
- https://api.ingrid.com
- Base url for Address API: https://api.ingrid.com/address/v1
- Swagger UI
- Swagger JSON
Object Reference
Address
Represents an address suitable for delivery.
| country_code 🔗 |
string
required
Refers to a ISO-3166 alpha 2 country code |
| region_code 🔗 |
string
Refers to an ISO-3166-2 subdivision code without country_code prefix, e.g., `DC` for Washington DC. Except for countries like México, Hong Kong, etc. Example region for Honk Kong - `Kowloon` |
| subregion_code 🔗 |
string
Refers to an ISO-3166-2 subdivision code without country_code prefix, e.g., `DC` for Washington DC. Except for countries like México, Hong Kong, etc. Example region for Honk Kong - `Kowloon` |
| postal_code 🔗 |
string
Refers to a postal code or zipcode |
| city 🔗 |
string
Refers to a city, postal_town or locality |
| address_lines 🔗 |
string[]
List of strings, each a part of the address, e.g., street name, street number, building name, floor |
| street 🔗 |
string
Street name of the address |
| street_number 🔗 |
string
Street number of the address |
| apartment_number 🔗 |
string
Apartment number of the address |
| building_name 🔗 |
string
Building name of the address |
| floor_number 🔗 |
string
Floor number of the address |
| po_box_id 🔗 |
string
PO Box identifier of the address |
| name 🔗 |
string
Full name associated with the address, for example company name |
| care_of 🔗 |
string
Care of information associated with the address |
| coordinates 🔗 |
Geolocation of the given address |
AddressSuggestionAddressComponentId
Enum Values:
- UNKNOWN
- ADDRESS_LINES
- ADDRESS_LINES_2
- CITY
- POSTAL_CODE
- COUNTRY
- REGION
- NAME
- STREET
- STREET_NUMBER
- APARTMENT_NUMBER
- PHONE_NUMBER
- FIRST_NAME
- LAST_NAME
- BUILDING_NAME
Any
| @type 🔗 |
string
|
Contact
Contact represents generic contact information.
| id 🔗 |
string
required
The identifier of the contact |
| address 🔗 |
Address
required
The physical address of the contact |
| email 🔗 |
string
The email address of the contact |
| phone_number 🔗 |
The phone number of the contact, including region and optional extension |
| name 🔗 |
string
Full name associated with the contact |
| first_name 🔗 |
string
First name associated with the contact |
| last_name 🔗 |
string
Last name associated with the contact |
| national_id_number 🔗 |
string
National ID number associated with the contact |
| company_name 🔗 |
string
Company name associated with the contact |
| vat 🔗 |
string
VAT number associated with the contact |
| customs_number 🔗 |
string
Customs number associated with the contact |
ContactPhoneNumber
A phone number, including region and optional extension.
| country_code 🔗 |
string
required
The country code where the delivery will occur (ISO 3166-1 alpha-2) |
| number 🔗 |
string
required
The main phone number, formatted as per the region's conventions |
| extension 🔗 |
string
An optional phone number extension |
ConvertSuggestionResponse
Response message for converted session.
Coordinates
Represents a latitude/longitude pair. Unless specified otherwise, this must conform to the WGS84 standard. Values must be within normalized ranges.
| lat 🔗 |
number
required
The latitude in degrees. Must be within the range -90.0 to +90.0, inclusive |
| lng 🔗 |
number
required
The longitude in degrees. Must be within the range -180.0 to +180.0, inclusive |
ListContactsResponse
Response message for listing customer saved contacts.
| id 🔗 |
string
The resource id of the set of contacts to retrieve. Typically this is the customer ID |
| contacts 🔗 |
object[]
A list of addresses in the address book |
ListSuggestionsResponse
| suggestions 🔗 |
object[]
|
ProviderId
External data provider for the suggestions and addresses.
- UNSPECIFIED: If the provider is unspecified or unknown, the default one will be used.
Enum Values:
- UNSPECIFIED
- GOOGLE_MAPS
- LOQATE
Status
Suggestion
A Suggestion represents address suggestion returned by an address autocomplete service.
| id 🔗 |
string
The identifier of the suggestion. Used to translate the suggestion into a full address in convert api |
| container_id 🔗 |
string
required
Identifier of the group of suggestions (eg "London, Tower Bridge Rd"). Used to fetch more details about the suggestion in ListSuggestions |
| display_line_1 🔗 |
string
required
Display line of the suggested address.<br/><br/>Example for simple address: display_line_1="1 Lanark Road" display_line_2="London W9 1DD"<br/><br/>Example for a container of addresses: display_line_1="Landmann Way" display_line_2="London SE14 - 38 Addresses" |
| display_line_2 🔗 |
string
|
| provider 🔗 |
ProviderId
required
|
ValidateAddressRequest
Request message for validating an address.
| address 🔗 |
Address
required
Address to be validated |
| provider 🔗 |
ProviderId is tge ID of the data provider to be used for validation. If not specified, the default one will be used |
| locales 🔗 |
string[]
Locales list defined as lc-CC compliant with ISO 3166-1, in order of preference - the first supported one will be chosen. If not specified, the default locale will be used. For `Google` it is "en-US". `Loqate` does not use locales |
ValidateAddressResponse
Response message for validating an address.
| result 🔗 |
VerifyResultType indicates whether the address is valid or not |
| suggestion 🔗 |
AddressSuggestion provides a suggested address if the original address is invalid |
ValidateAddressResponseAddressSuggestion
ValidateAddressResponseVerifyResultType
Enum Values:
- UNKNOWN
- VALID
- INVALID