{
"openapi": "3.0.1",
"info": {
"title": "Address APIs",
"description": "The Address APIs provide capabilities to validate, standardize, and suggest addresses to improve delivery accuracy and reduce shipment failures. These APIs help ensure that addresses used in shipment processing are complete, correctly formatted, and aligned with postal standards.\nThe APIs support:\n - Address Validation (domestic and international) to verify and correct address data\n - Address Suggestion to provide alternatives when validation fails\n - Address Autocomplete to assist in capturing accurate addresses from partial input\n",
"version": "1.0.0"
},
"servers": [
{
"url": "https://api-sandbox.sendpro360.pitneybowes.com/shipping",
"description": "Sandbox Server"
},
{
"url": "https://api.sendpro360.pitneybowes.com/shipping",
"description": "Production Server (uses live data)"
}
],
"tags": [
{
"name": "Address",
"description": "APIs for validating, suggesting, and autocompleting addresses.\n- Standardizes address formats based on postal data\n- Enhances delivery accuracy by correcting address components\n- Provides fallback mechanisms (suggestions) when validation fails\n- Supports user-friendly address capture through autocomplete\n"
}
],
"paths": {
"/api/v1/address/verify": {
"post": {
"tags": [
"Address"
],
"summary": "Address Validate",
"description": "This operation validates addresses to improve postal accuracy within the country (e.g., United States). This ensure that parcels are rated correctly and shipments reach their final destination on time. The validate address operation sends an address for verification, and the response indicates whether the address is valid.
\n**Key Considerations:** \n\n- Validation results include `VALIDATED_AND_NOT_CHANGED or VALIDATED_CHANGED` for valid addresses. Invalid addresses result in HTTP status 400 with an Error Code of `Invalid Address`.\n- Only U.S. domestic addresses are validated.\n- Pitney Bowes verifies addresses for accuracy against current USPS® data and makes corrections to delivery lines and last lines when possible.\n- The `minimalAddressValidation` query parameter can be used to limit the extent of corrections to the address.\n- If validation fails, you can use the [Suggest Addresses API](/openapi/address/address/addresssuggest) call to provide suggestions that could result in the address passing verification in a subsequent Address Validation API call.\n",
"operationId": "addressValidate",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/addressValidateRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "The address has been verified.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/addressValidateResponse"
},
"examples": {
"response": {
"value": {
"addressLine1": "27 Waterview Drive",
"addressLine2": "near abc street",
"addressLine3": "near xyz street",
"cityTown": "Shelton",
"countryCode": "US",
"name": "John Smith",
"postalCode": "06484-5841",
"residential": true,
"stateProvince": "CT",
"status": "VALIDATED_AND_NOT_CHANGED",
"deliveryPoint": "57",
"carrierRoute": "C005"
}
}
}
}
}
},
"400": {
"description": "Invalid or Bad Request",
"$ref": "#/components/responses/BadRequestError"
},
"401": {
"description": "Unauthorized Error",
"$ref": "#/components/responses/UnauthorizedError"
},
"500": {
"description": "Internal Server Error",
"$ref": "#/components/responses/InternalServerError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/address/suggest": {
"post": {
"tags": [
"Address"
],
"summary": "Address Suggest",
"description": "The Address Suggest API returns address suggestions. Use this API only if the [Address Validate API](/openapi/address/address/addressvalidate) fails to validate an address and returns a 400 error. This API itself does not validate addresses; it returns suggestions based on the information submitted in the request. \n\n**Important Notes**\n\n - In response, the address object outside the suggestions object, including the status field, must be ignored as it does not provide valid address data.\n\n - Only the `addresses` listed under the `suggestions.addresses` array should be considered for further action.\n\n **Key Considerations**\n\n - Some suggestions, especially for range suggestions, might not be valid delivery points may not guarantee delivery.\n For example, if the suggested valid range for a street is 1-100, the API may suggest and validate all numbers in the range, even if only 12, 24, and 36 are actual deliverable addresses.\n\n - The API returns a maximum of 20 suggestions.\n\n - The suggestions are not sorted by best match.\n\n - Some requests might return no suggestions.\n\n - If no suggestions are available, the suggestions object is not included in the response.\n",
"operationId": "addressSuggest",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/addressSuggestRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "The address is suggested to use.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/addressSuggestResponse"
}
}
}
},
"400": {
"description": "Invalid or Bad Request",
"$ref": "#/components/responses/BadRequestError"
},
"401": {
"description": "Unauthorized Error",
"$ref": "#/components/responses/UnauthorizedError"
},
"500": {
"description": "Internal Server Error",
"$ref": "#/components/responses/InternalServerError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v2/address/suggest": {
"get": {
"tags": [
"Address"
],
"summary": "Address Autocomplete",
"description": "The Address Autocomplete API provides intelligent address suggestions for U.S. addresses based on partial input submitted in the searchText query parameter. It returns a structured list of up to 15 suggested addresses, including unit-level details (e.g., apartments or suites) and geographic coordinates when available.
\nUse [Address Validate API](/openapi/address/address/addressvalidate) to validate the address. \n\n\n**Key Capabilities:**\n- Returns full, structured addresses based on `searchText`
\n- Accepts partial address details such as a street name, city, state, or ZIP code.
\n- Autocompletes partial addresses and place names, prioritizing results by relevance and proximity.
\n- Suggests unit-level suggestions when available (e.g., apartments, suites)
\n- Provides geographic coordinates (latitude and longitude) for mapping use cases.
\n- Returns up to 15 relevant address suggestions per request\n\n> Note: This API only suggests addresses matches. It does **not** validate them. To verify address accuracy, use the [Address Validation API](/openapi/address/address/addressvalidate).\n",
"operationId": "addressAutocomplete",
"parameters": [
{
"name": "searchText",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "The partial address text to autocomplete such as a street name, city, state, or postal code. For example if you search `1600 Penn`, the API returns `1600 Pennsylvania Ave, McDonough, GA 30253` along with other relevant U.S. address suggestions to choose from."
},
{
"name": "country",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "The country code (As of now only supported for US)."
}
],
"security": [
{
"bearerAuth": []
}
],
"responses": {
"200": {
"description": "A list of address suggestions has been retrived.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddressAutocomplete"
}
}
}
},
"400": {
"description": "Invalid or Bad Request",
"$ref": "#/components/responses/BadRequestError"
},
"401": {
"description": "Unauthorized Error",
"$ref": "#/components/responses/UnauthorizedError"
},
"500": {
"description": "Internal Server Error",
"$ref": "#/components/responses/InternalServerError"
}
}
}
},
"/api/v1/address/verify/intl": {
"post": {
"tags": [
"Address"
],
"summary": "International Address Validate",
"description": "This operation validates international addresses to improve postal accuracy within that country. This ensure that parcels are rated correctly and shipments reach their final destination on time. The International Address Validate operation sends an address for verification, and the response indicates whether the address is valid.
\n**Key Considerations:** \n\n- Validation results include `VALIDATED_AND_NOT_CHANGED or VALIDATED_CHANGED` for valid addresses. Invalid addresses result in HTTP status 400 with an Error Code of `Invalid Address`.\n",
"operationId": "addressValidateIntl",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddressValidateINTLRequest"
},
"example": {
"addressLine1": "638 Manitobazz",
"cityTown": "Winnipeg",
"countryCode": "CA",
"name": "Paul Wright",
"phone": "203-555-1213",
"postalCode": "R2W 2H1",
"residential": false,
"stateProvince": "AB"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "The address has been verified.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddressValidateINTLResponse"
},
"example": {
"addressLine1": "638 Manitoba Ave",
"addressLine2": "",
"addressLine3": "",
"cityTown": "Winnipeg",
"countryCode": "CA",
"name": "",
"postalCode": "R2W 2H1",
"residential": false,
"stateProvince": "MB",
"status": "VALIDATED_CHANGED"
}
}
}
},
"400": {
"description": "Invalid or Bad Request",
"$ref": "#/components/responses/BadRequestError"
},
"401": {
"description": "Unauthorized Error",
"$ref": "#/components/responses/UnauthorizedError"
},
"500": {
"description": "Internal Server Error",
"$ref": "#/components/responses/InternalServerError"
}
},
"security": [
{
"bearerAuth": []
}
]
}
}
},
"components": {
"schemas": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "This is HTTP 401 Unauthorized response status code, that indicates that the client request has not been completed because it lacks valid authentication credentials for the requested resource."
}
},
"required": [
"message"
]
},
"Errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"errorCode": {
"type": "string",
"description": "Error code(s) that appear due to HTTP 400- Invalid or Bad Request, e.g. validation-error.",
"example": "validation_error"
},
"errorDescription": {
"type": "string",
"description": "The HTTP 400 Bad Request response status code indicates that the server cannot process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).",
"example": "Error while geting rates for carrier with carrierAccount eRMnRx4mzPP."
},
"additionalCode": {
"type": "string",
"description": "A unique identifier for the error, for example 1101055, 0100008, or 1021126."
},
"additionalInfo": {
"type": "string",
"description": "This is an additional information about the error. This error 'Invalid Request' might appear due to invalid dimension, weight, or serviceid, or if the information is missing."
},
"additionalParameters": {
"type": "array",
"items": {
"type": "string",
"description": "The field(s) that might be incorrect in the request."
}
}
}
}
},
"NotFoundErrors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"errorCode": {
"type": "string",
"example": "not_found",
"description": "Error code(s) that appear due HTTP 404 Page or File not found."
},
"errorDescription": {
"type": "string",
"example": "resource not found",
"description": "The HTTP 404 Not Found response status code indicates that the server cannot find the requested resource."
},
"additionalCode": {
"type": "string",
"description": "A unique identifier for the error, for example 0100025, 1110017, or 1090001."
},
"additionalInfo": {
"type": "string",
"description": "Additional information about the error. This error 'Not Found' might appear due to `Shipment Not Found`, `No Shipments to close`, or `Original Transaction not found`."
},
"additionalParameters": {
"type": "array",
"items": {
"type": "string",
"description": "The field(s) that might be incorrect in the request."
}
}
}
}
},
"addressSuggestRequest": {
"type": "object",
"required": [
"address"
],
"properties": {
"address": {
"type": "object",
"required": [
"addressLine1",
"cityTown",
"countryCode",
"postalCode",
"stateProvince"
],
"properties": {
"addressLine1": {
"type": "string",
"description": "The addressLine1 can contain the Flat number, Building or Apartment Name/number (if any) or company name (if not residential).",
"example": "27 Watervw Dr"
},
"addressLine2": {
"type": "string",
"description": "The addressLine2 contains Street address or Landmark (if any). ",
"example": ""
},
"addressLine3": {
"type": "string",
"description": "The addressLine3 contains P.O.Box (if any) near the address.",
"example": ""
},
"cityTown": {
"type": "string",
"description": "The name of the city or town to where the address belongs.",
"example": "Shelton"
},
"countryCode": {
"type": "string",
"description": "This indicates the two-character ISO code of the country from the ISO country list.",
"example": "US"
},
"name": {
"type": "string",
"description": "Name of the person to which this address points.",
"example": "John Smith"
},
"postalCode": {
"type": "string",
"description": "The postal code or ZIP code of the address. For US addresses, use either the 5-digit or 9-digit ZIP code in one of the following formats: '12345' or '12345-6789'. If you use a different format, such as 12345- or 123451234, will receive an error.",
"example": "06484"
},
"stateProvince": {
"type": "string",
"description": "The State or Province of the address.",
"example": "CT"
}
}
}
}
},
"addressSuggestResponse": {
"type": "object",
"properties": {
"address": {
"type": "object",
"properties": {
"addressLine1": {
"type": "string",
"description": "The addressLine1 can contain the Flat number, Building or Apartment Name/number (if any) or company name (if not residential).",
"example": "27 Watervw Dr"
},
"addressLine2": {
"type": "string",
"description": "The addressLine2 contains Street address or Landmark (if any).",
"example": "near abc street"
},
"addressLine3": {
"type": "string",
"description": "The addressLine3 contains P.O.Box (if any) near the address.",
"example": "near xyz street"
},
"cityTown": {
"type": "string",
"description": "The name of the city or town to where the address belongs.",
"example": "Shelton"
},
"countryCode": {
"type": "string",
"description": "This indicates the two-character ISO code of the country from the ISO country list.",
"example": "US"
},
"name": {
"type": "string",
"description": "Name of the person to which this address points.",
"example": "John Smith"
},
"postalCode": {
"type": "string",
"description": "The Postal Code or ZIP code of the address. For US addresses, use either the 5-digit or 9-digit ZIP code in one of the following formats: '12345' or '12345-6789'. If you use a different format, such as 12345- or 123451234, will receive an error.",
"example": "06484"
},
"residential": {
"type": "boolean",
"description": "The specified adress can be Residential or Official. In case if the adress is Residential, the boolean value will be 'true', else it will take 'false'.",
"example": "false"
},
"stateProvince": {
"type": "string",
"description": "The State or Province of the address. For a US or Canadian address, it is the 2-letter state or province code. ",
"example": "CT"
},
"status": {
"type": "string",
"example": "VALIDATED_CHANGE"
},
"deliveryPoint": {
"type": "string",
"description": "The 2-digit USPS delivery point code for the address. It is used to specify delivery locations within a postal route.\n- Supported Carrier: USPS domestic shipments only.\n",
"example": "57"
},
"carrierRoute": {
"type": "string",
"description": "The 4-character alphanumeric carrier route code. It is used to specify delivery route for a specific mail carrier.\n- Full carrier route codes include the 5-digit ZIP Code followed by the 4-character carrierRoute (e.g., `12345C005`).\n- Supported Carrier: USPS domestic shipments only.\n",
"example": "C005"
}
}
},
"suggestions": {
"type": "object",
"properties": {
"suggestionType": {
"type": "string",
"description": "The part of the address that is changed in the accompanying suggestions. Possible values are: - street - streetPrimaryRange (e.g., street number, PO Box number) - secondaryRange (e.g., suite number, apartment number) - PO BoxPrimaryRange - ruralRouteUnitRange - highwayContractUnitRange - city - company - puertoricanUrbanization",
"example": " "
},
"addresses": {
"type": "array",
"items": {
"type": "object",
"properties": {
"addressLine1": {
"type": "string",
"description": "The addressLine1 can contain the Flat number, Building or Apartment Name/number (if any) or company name (if not residential).",
"example": "27 Watervw Dr"
},
"addressLine2": {
"type": "string",
"description": "The addressLine2 contains Street address or Landmark (if any).",
"example": "near abc street"
},
"addressLine3": {
"type": "string",
"description": "The addressLine3 contains P.O.Box (if any) near the address.",
"example": "near xyz street"
},
"cityTown": {
"type": "string",
"description": "The name of the city or town to where the address belongs.",
"example": "Shelton"
},
"name": {
"type": "string",
"description": "Name of the person to which this address points.",
"example": "John Smith"
},
"postalCode": {
"type": "string",
"description": "The postal code or ZIP code of the address. For US addresses, use either the 5-digit or 9-digit ZIP code in one of the following formats: '12345' or '12345-6789'. If you use a different format, such as 12345- or 123451234, will receive an error.",
"example": "06484"
},
"residential": {
"type": "boolean",
"description": "The specified adress can be Residential or Official. In case if the adress is Residential, the boolean value will be 'true', else it will take 'false'.",
"example": "false"
},
"stateProvince": {
"type": "string",
"description": "The State or Province of the address. For a US or Canadian address, it is the 2-letter state or province code. ",
"example": "CT"
},
"deliveryPoint": {
"type": "string",
"description": "The 2-digit USPS delivery point code for the address. It is used to specify delivery locations within a postal route.\n- Supported Carrier: USPS domestic shipments only.\n",
"example": "57"
},
"carrierRoute": {
"type": "string",
"description": "The 4-character alphanumeric carrier route code. It is used to specify delivery route for a specific mail carrier.\n- Full carrier route codes include the 5-digit ZIP Code followed by the 4-character carrierRoute (e.g., `12345C005`).\n- Supported Carrier: USPS domestic shipments only.\n",
"example": "C005"
}
}
}
}
}
}
}
},
"addressValidateRequest": {
"type": "object",
"required": [
"addressLine1",
"postalCode",
"countryCode"
],
"properties": {
"addressLine1": {
"type": "string",
"description": "The addressLine1 can contain the Flat number, Building or Apartment Name/number (if any) or company name (if not residential).",
"example": "27 Watervw Dr"
},
"addressLine2": {
"type": "string",
"description": "The addressLine2 contains Street address or Landmark (if any).",
"example": "near abc street"
},
"addressLine3": {
"type": "string",
"description": "The addressLine3 contains P.O.Box (if any) near the address.",
"example": "near xyz street"
},
"cityTown": {
"type": "string",
"description": "The name of the city or town to where the address belongs.",
"example": "Shelton"
},
"countryCode": {
"type": "string",
"description": "This indicates the two-character ISO code of the country from the ISO country list.",
"example": "US"
},
"name": {
"type": "string",
"description": "Name of the person to which this address points.",
"example": "John Smith"
},
"postalCode": {
"type": "string",
"description": "The postal code or ZIP code of the address. For US addresses, use either the 5-digit or 9-digit ZIP code in one of the following formats: '12345' or '12345-6789'. If you use a different format, such as 12345- or 123451234, will receive an error.",
"example": "06484"
},
"stateProvince": {
"type": "string",
"description": "The State or Province of the address. For a US or Canadian address, it is the 2-letter state or province code. ",
"example": "CT"
}
}
},
"addressValidateResponse": {
"type": "object",
"properties": {
"addressLine1": {
"type": "string",
"description": "The addressLine1 can contain the Flat number, Building or Apartment Name/number (if any) or company name (if not residential).",
"example": "27 Watervw Dr"
},
"addressLine2": {
"type": "string",
"description": "The addressLine2 contains Street address or Landmark (if any).",
"example": "near abc street"
},
"addressLine3": {
"type": "string",
"description": "The addressLine3 contains P.O.Box (if any) near the address.",
"example": "near xyz street"
},
"cityTown": {
"type": "string",
"description": "The name of the city or town to where the address belongs.",
"example": "Shelton"
},
"countryCode": {
"type": "string",
"description": "This indicates the two-character ISO code of the country from the ISO country list.",
"example": "US"
},
"name": {
"type": "string",
"description": "Name of the person to which this address points.",
"example": "John Smith"
},
"postalCode": {
"type": "string",
"description": "The postal code or ZIP code of the address. For US addresses, use either the 5-digit or 9-digit ZIP code in one of the following formats: '12345' or '12345-6789'. If you use a different format, such as 12345- or 123451234, will receive an error.",
"example": "06484"
},
"residential": {
"type": "boolean",
"description": "The specified adress can be Residential or Official. In case if the adress is Residential, the boolean value will be 'true', else it will take 'false'.",
"example": true
},
"stateProvince": {
"type": "string",
"description": "The State or Province of the address. For a US or Canadian address, it is the 2-letter state or province code. ",
"example": "CT"
},
"deliveryPoint": {
"type": "string",
"description": "The 2-digit USPS delivery point code for the address. It is used to specify delivery locations within a postal route.\n- Supported Carrier: USPS domestic shipments only.\n",
"example": "57"
},
"carrierRoute": {
"type": "string",
"description": "The 4-character alphanumeric carrier route code. It is used to specify delivery route for a specific mail carrier.\n- Full carrier route codes include the 5-digit ZIP Code followed by the 4-character carrierRoute (e.g., `12345C005`).\n- Supported Carrier: USPS domestic shipments only.\n",
"example": "C005"
},
"status": {
"type": "string",
"enum": [
"VALIDATED_CHANGED",
"VALIDATED_AND_NOT_CHANGED"
],
"description": ">- This field applies only to the Validate Address API. It indicates whether the submitted address is valid and whether the API made significant changes to the address. Possible values are:
-`VALIDATED_CHANGED`: The address is valid, but the API made significant changes to improve it. For example, if an address includes a valid street number and street name (e.g., 100 Elm) but is missing a street suffix (e.g., St), the API would add the suffix. Adding or changing the Zip+4, suite or unit number, residential flag, or making formatting changes are not considered significant changes.
-`VALIDATED_AND_NOT_CHANGED`: The address is valid, and the API made no significant changes.",
"example": "VALIDATED_CHANGED"
}
}
},
"AddressAutocomplete": {
"type": "object",
"description": "Response object containing suggested address results based on input query.",
"properties": {
"location": {
"type": "array",
"description": "An array of suggested address candidates.",
"items": {
"type": "object",
"properties": {
"totalUnitCount": {
"type": "integer",
"description": "Number of unit-level addresses found for the main address.",
"example": 3
},
"address": {
"type": "object",
"description": "Details of the primary suggested address, including display formatting and parsed components.",
"properties": {
"formattedAddress": {
"type": "string",
"description": "Full formatted version of the address.",
"example": "27 Water St, Hallowell, ME 04347"
},
"suggestedFormattedAddress": {
"type": "string",
"description": "Alternate formatted region-specific representation of the address.",
"example": "ME 04347, 27 Water St, Hallowell"
},
"mainAddressLine": {
"type": "string",
"description": "Primary address line containing street number and street name.",
"example": "27 Water St"
},
"addressLastLine": {
"type": "string",
"description": "The addressLine1 contains concatenation of city, state, and postal code.",
"example": "Hallowell, ME 04347"
},
"areaName1": {
"type": "string",
"description": "The top-level administrative division (e.g., state or province) of the address.",
"example": "ME"
},
"areaName3": {
"type": "string",
"description": "The city, town, or locality where the address is located.",
"example": "Hallowell"
},
"postCode": {
"type": "string",
"description": "Postal code (ZIP code) of the address.",
"example": "04347"
},
"country": {
"type": "string",
"description": "The ISO 3166-1 alpha-2 country code.",
"example": "US"
},
"addressNumber": {
"type": "string",
"description": "Street number component of the address.",
"example": "27"
},
"streetName": {
"type": "string",
"description": "The name of the street where the address is located.",
"example": "Water St"
}
}
},
"geometry": {
"type": "object",
"description": "Geographic location metadata for the suggested address.",
"properties": {
"type": {
"type": "string",
"description": "Geometry type used to define the location (Point for a set of coordinates).",
"example": "Point"
},
"coordinates": {
"type": "array",
"description": "Geographic coordinates [latitude, longitude] representing the address.",
"items": {
"type": "number"
},
"example": [
44.29344,
-69.786861
]
}
}
},
"ranges": {
"type": "array",
"description": "List of unit-level groupings (e.g., apartments or suites) associated with the suggested address.",
"items": {
"type": "object",
"properties": {
"units": {
"type": "array",
"description": "Unit-level breakdowns of the main address, including formatted and suggested addresses.",
"items": {
"type": "object",
"properties": {
"unitInfo": {
"type": "string",
"description": "Unit identifier such as apartment, suite, or flat number.",
"example": "Apt 1"
},
"formattedUnitAddress": {
"type": "string",
"description": "Fully formatted address including main address and unit information.",
"example": "27 Water St, Apt 1, Hallowell, ME 04347"
},
"suggestedAddress": {
"type": "object",
"description": "The structured form of the suggested unit-level address.",
"properties": {
"addressLine1": {
"type": "string",
"description": "The primary address line (street and unit information).",
"example": "27 Water St, Apt 1"
},
"addressLine2": {
"type": "string",
"description": "Secondary address line (internal routing or extended info).",
"example": ""
},
"city": {
"type": "string",
"description": "Name of the city or town.",
"example": "Hallowell"
},
"state": {
"type": "string",
"description": "State or administrative region.",
"example": "ME"
},
"postalCode": {
"type": "string",
"description": "ZIP or postal code.",
"example": "04347"
},
"suggestedFormattedAddress": {
"type": "string",
"description": "A recommended format for the full address.",
"example": "ME 04347, 27 Water St, Apt 1, Hallowell"
}
}
}
}
}
}
}
}
}
}
}
}
}
},
"AddressValidateINTLRequest": {
"type": "object",
"required": [
"addressLine1",
"postalCode",
"countryCode"
],
"properties": {
"addressLine1": {
"type": "string",
"description": "The addressLine1 can contain the Flat number, Building or Apartment Name/number (if any) or company name (if not residential).",
"example": "27 Watervw Dr"
},
"addressLine2": {
"type": "string",
"description": "The addressLine2 contains Street address or Landmark (if any).",
"example": "near abc street"
},
"addressLine3": {
"type": "string",
"description": "The addressLine3 contains P.O.Box (if any) near the address.",
"example": "near xyz street"
},
"cityTown": {
"type": "string",
"description": "The name of the city or town to where the address belongs.",
"example": "Shelton"
},
"countryCode": {
"type": "string",
"description": "This indicates the two-character ISO code of the country from the ISO country list.",
"example": "US"
},
"name": {
"type": "string",
"description": "Name of the person to which this address points.",
"example": "John Smith"
},
"postalCode": {
"type": "string",
"description": "The postal code or ZIP code of the address.",
"example": "06484"
},
"stateProvince": {
"type": "string",
"description": "The State or Province of the address. For a US or Canadian address, it is the 2-letter state or province code. ",
"example": "CT"
}
}
},
"AddressValidateINTLResponse": {
"type": "object",
"properties": {
"addressLine1": {
"type": "string",
"description": "The addressLine1 can contain the Flat number, Building or Apartment Name/number (if any) or company name (if not residential).",
"example": "27 Watervw Dr"
},
"addressLine2": {
"type": "string",
"description": "The addressLine2 contains Street address or Landmark (if any).",
"example": "near abc street"
},
"addressLine3": {
"type": "string",
"description": "The addressLine3 contains P.O.Box (if any) near the address.",
"example": "near xyz street"
},
"cityTown": {
"type": "string",
"description": "The name of the city or town to where the address belongs.",
"example": "Shelton"
},
"countryCode": {
"type": "string",
"description": "This indicates the two-character ISO code of the country from the ISO country list.",
"example": "US"
},
"name": {
"type": "string",
"description": "Name of the person to which this address points.",
"example": "John Smith"
},
"postalCode": {
"type": "string",
"description": "The postal code or ZIP code of the address. For US addresses, use either the 5-digit or 9-digit ZIP code in one of the following formats: '12345' or '12345-6789'. If you use a different format, such as 12345- or 123451234, will receive an error.",
"example": "06484"
},
"residential": {
"type": "boolean",
"description": "The specified adress can be Residential or Official. In case if the adress is Residential, the boolean value will be 'true', else it will take 'false'.",
"example": true
},
"stateProvince": {
"type": "string",
"description": "The State or Province of the address. For a US or Canadian address, it is the 2-letter state or province code. ",
"example": "CT"
},
"deliveryPoint": {
"type": "string",
"description": "The 2-digit USPS delivery point code for the address. It is used to specify delivery locations within a postal route.\n- Supported Carrier: USPS domestic shipments only.\n",
"example": "57"
},
"carrierRoute": {
"type": "string",
"description": "The 4-character alphanumeric carrier route code. It is used to specify delivery route for a specific mail carrier.\n- Full carrier route codes include the 5-digit ZIP Code followed by the 4-character carrierRoute (e.g., `12345C005`).\n- Supported Carrier: USPS domestic shipments only.\n",
"example": "C005"
},
"status": {
"type": "string",
"enum": [
"VALIDATED_CHANGED",
"VALIDATED_AND_NOT_CHANGED"
],
"description": ">- This field applies only to the Validate Address API. It indicates whether the submitted address is valid and whether the API made significant changes to the address. Possible values are:
-`VALIDATED_CHANGED`: The address is valid, but the API made significant changes to improve it. For example, if an address includes a valid street number and street name (e.g., 100 Elm) but is missing a street suffix (e.g., St), the API would add the suffix. Adding or changing the Zip+4, suite or unit number, residential flag, or making formatting changes are not considered significant changes.
-`VALIDATED_AND_NOT_CHANGED`: The address is valid, and the API made no significant changes.",
"example": "VALIDATED_CHANGED"
}
}
}
},
"responses": {
"UnauthorizedError": {
"description": "The request could not be authorized.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error"
}
}
}
},
"InternalServerError": {
"description": "The request could not be completed due to an internal error.",
"content": {}
},
"BadRequestError": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
}
}
}
},
"NotFoundError": {
"description": "The requested resource was not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotFoundErrors"
}
}
}
}
},
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer"
}
}
}
}