{ "openapi": "3.0.3", "info": { "version": "1.0.0", "title": "extpartneromnisvcsms", "description": "This is OpenAPI Spec APIs for external partners to perform address validation.", "contact": { "name": "Omni API Support", "email": "DL-OmniAdapter@att.com" } }, "servers": [ { "url": "https://partner.att.com/omni-svcs" } ], "tags": [ { "name": "omni-svcs-address-validation", "description": "omni service address validation" } ], "paths": { "/v1/address": { "post": { "tags": [ "omni-svcs-address-validation" ], "description": "Address Supported are PPU, Billing, Shipping", "summary": "Perform Address Validation", "operationId": "ValidateAddress", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressValidationRequest" }, "examples": { "Address_Validation_With AddressLine2": { "value": { "geographicAddress": { "addressLine1": "23114 38th Ave SE", "addressLine2": "APT 123", "addressType": "Shipping, Billing", "city": "CHOLA VISTA", "postalcode": "98021", "stateOrProvince": "WA" } } }, "Address_Validation_with_Type_Rural_Address": { "value": { "geographicAddress": { "addressLine1": "RR 2 BOX 18", "addressType": "Billing", "postalcode": "77437", "city": "EL CAMPO", "stateOrProvince": "TX" } } }, "Address_Validation_Close_Match": { "value": { "geographicAddress": { "addressLine1": "3400 w plano pkwu", "addressType": "PPU", "postalcode": "75075", "city": "Plano", "stateOrProvince": "TX" } } } } } } }, "responses": { "200": { "description": "Return Address Validation Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressValidationResponse" }, "examples": { "Success_Response": { "value": { "validationResult": "success", "validationResultCode": "4S80", "validGeographicAddress": { "id": "00000NG3XH", "streetNr": "3802", "streetName": "MAIN", "streetType": "ST", "city": "CHULA VISTA", "stateOrProvince": "CA", "postcode": "91911", "postcodeExtension": "6247", "streetSuffix": "SE", "geographicSubAddress": [ { "subUnitType": "STE", "subUnitNumber": "5", "subAddressType": "H" } ], "addressCharacteristic": [ { "name": "addressLine1", "value": "3802 MAIN ST STE 5" }, { "name": "cityAbbreviatedName", "value": "CHULA VISTA" }, { "name": "cassAddressLine1", "value": "2400 BRIARWEST BLVD" }, { "name": "cassAddressLine2", "value": "HOUSTON TX 77077-7601" }, { "name": "county", "value": "COOK" }, { "name": "urbanizationCode", "value": "URB SUMMIT HLS" }, { "name": "addressMatchCode", "value": "3SUU" }, { "name": "addressMatchCodeDescription", "value": "Unit information is not recognized by the U.S. Postal Service. Mail may not be delivered" }, { "name": "addressMatchCodeStatus", "value": "S80000" }, { "name": "deliveryPointValidationCode", "value": "S" }, { "name": "lacsCode", "value": "F" }, { "name": "deliveryPointValidationFootnote", "value": "AABBCC" }, { "name": "taxationGeocode", "value": "0144339144000" }, { "name": "latitude", "value": "29.738805" }, { "name": "longitude", "value": "-95.61404" } ] }, "validationTypeRecommendation": [ { "validationType": "BILLING", "validationRecommendation": "ACCEPT" }, { "validationType": "SHIPPING", "validationRecommendation": "ACCEPT" } ] } }, "Close_Match_Multiple_Matches_Response": { "value": { "validationResult": "success", "validationResultCode": "4SPO", "validGeographicAddress": { "id": "00011JCNHB", "streetName": "PO BOX 1600", "city": "HILO", "stateOrProvince": "HI", "postcode": "96721", "postcodeExtension": "1600", "geographicSubAddress": [ { "subAddressType": "P" } ], "addressCharacteristic": [ { "name": "addressLine1", "value": "PO BOX 1600" }, { "name": "cassAddressLine1", "value": "PO BOX 1600" }, { "name": "cassAddressLine2", "value": "HILO HI 96721-1600" }, { "name": "cityAbbreviatedName", "value": "HILO" }, { "name": "county", "value": "HAWAII" }, { "name": "addressMatchCode", "value": "4SPO" }, { "name": "addressMatchCodeDescription", "value": "This is a PO Box, not a physical address" }, { "name": "addressMatchCodeStatus", "value": "S80000" }, { "name": "deliveryPointValidationCode", "value": "Y" }, { "name": "lacsCode", "value": "false" }, { "name": "deliveryPointValidationFootnote", "value": "AABB" }, { "name": "taxationGeocode", "value": "0112001004000" }, { "name": "latitude", "value": "19.725549" }, { "name": "longitude", "value": "-155.088617" }, { "name": "postalBox", "value": "1600" } ] }, "validationTypeRecommendation": [ { "validationType": "BILLING", "validationRecommendation": "ACCEPT" }, { "validationType": "SHIPPING", "validationRecommendation": "STOP" } ] } }, "Partial_Match_with_Recommendation_Response": { "value": { "validationResult": "closematch", "validationResultCode": "Multiple", "validationResultDescription": "Address validation found multiple matches", "alternateGeographicAddress": [ { "city": "PLANO", "stateOrProvince": "TX", "postcode": "75075", "postcodeExtension": "8011", "addressCharacteristic": [ { "name": "addressLine1", "value": "3400 W PLANO PKWY" }, { "name": "cassAddressLine1", "value": "2400 BRIARWEST BLVD" }, { "name": "cassAddressLine2", "value": "HOUSTON TX 77077-7601" }, { "name": "county", "value": "COOK" }, { "name": "urbanizationCode", "value": "URB SUMMIT HLS" }, { "name": "addressMatchCode", "value": "3SUU" }, { "name": "addressMatchCodeDescription", "value": "Unit information is not recognized by the U.S. Postal Service. Mail may not be delivered" }, { "name": "addressMatchCodeStatus", "value": "S80000" }, { "name": "deliveryPointValidationCode", "value": "S" }, { "name": "lacsCode", "value": "F" }, { "name": "deliveryPointValidationFootnote", "value": "AABBCC" }, { "name": "taxationGeocode", "value": "0144339144000" }, { "name": "latitude", "value": "29.738805" }, { "name": "longitude", "value": "-95.61404" } ] }, { "city": "PLANO", "stateOrProvince": "TX", "postcode": "75074", "postcodeExtension": "7203", "addressCharacteristic": [ { "name": "addressLine1", "value": "3400 E PLANO PKWY" }, { "name": "cassAddressLine1", "value": "2400 BRIARWEST BLVD" }, { "name": "cassAddressLine2", "value": "HOUSTON TX 77077-7601" }, { "name": "county", "value": "COOK" }, { "name": "urbanizationCode", "value": "URB SUMMIT HLS" }, { "name": "addressMatchCode", "value": "3SUU" }, { "name": "addressMatchCodeDescription", "value": "Unit information is not recognized by the U.S. Postal Service. Mail may not be delivered" }, { "name": "addressMatchCodeStatus", "value": "S80000" }, { "name": "deliveryPointValidationCode", "value": "S" }, { "name": "lacsCode", "value": "F" }, { "name": "deliveryPointValidationFootnote", "value": "AABBCC" }, { "name": "taxationGeocode", "value": "0144339144000" }, { "name": "latitude", "value": "29.738805" }, { "name": "longitude", "value": "-95.61404" } ] } ], "validationTypeRecommendation": [ { "validationType": "BILLING", "validationRecommendation": "LIST" }, { "validationType": "SHIPPING", "validationRecommendation": "LIST" } ] } }, "No_Match_Response": { "value": { "validationResult": "nomatch", "validationResultCode": "2E010", "validationResultDescription": "Incorrect or missing city+state or ZIP Code.", "validationTypeRecommendation": [ { "validationType": "BILLING", "validationRecommendation": "STOP" }, { "validationType": "SHIPPING", "validationRecommendation": "STOP" } ] } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "validation": { "$ref": "#/components/schemas/Validation" }, "error": { "$ref": "#/components/schemas/Error" } } } } } } } } } }, "components": { "schemas": { "AddressValidationRequest": { "type": "object", "properties": { "geographicAddress": { "$ref": "#/components/schemas/GeographicAddress" } } }, "GeographicAddress": { "type": "object", "properties": { "addressLine1": { "type": "string", "description": "Name of the street or other street type" }, "addressLine2": { "type": "string", "description": "Number identifying a specific property on a public street. It may be combined with streetNrLast for ranged addresses" }, "addressType": { "type": "string", "description": "Billing,Shipping,PPU. allows multiple values seperated by comma " }, "city": { "type": "string", "description": "City that the address is in" }, "postalcode": { "type": "string", "description": "descriptor for a postal delivery area, used to speed and simplify the delivery of mail (also know as zipcode)" }, "stateOrProvince": { "type": "string", "description": "the State or Province that the address is in" } }, "required": [ "addressType" ], "description": "Structured textual way of describing how to find a Property in an urban area (country properties are often defined differently).\nNote : Address corresponds to SID UrbanPropertyAddress" }, "AddressValidationResponse": { "type": "object", "properties": { "validationResult": { "type": "string", "description": "Result of the address validation (success, closematch, closematch-mdu, nomatch, fails)" }, "validationResultCode": { "type": "string", "description": "Address Match Code." }, "validationResultDescription": { "type": "string", "description": "Gives the description for the validationResultCode." }, "validGeographicAddress": { "$ref": "#/components/schemas/validGeographicAddress" }, "alternateGeographicAddress": { "type": "array", "items": { "$ref": "#/components/schemas/AlternateGeographicAddress" }, "description": "Populated with the list of addresses if there are multiple matches or MDU (Multiple Dwelling Units)" }, "validationTypeRecommendation": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationTypeRecommendation" } } }, "description": "This resource is used to manage address validation response", "title": "" }, "ValidationTypeRecommendation": { "type": "object", "properties": { "validationType": { "type": "string", "enum": [ "BILLING", "SHIPPING", "PPU" ] }, "validationRecommendation": { "type": "string", "enum": [ "ACCEPT", "LIST", "WARN", "STOP" ], "description": "ACCEPT: The calling application should allow the user to proceed with the validated address. LIST: The calling application should list the addresses returned by the mS and allow the user to select one and continue or enter a different address that is subsequently validated. WARN: The calling application should require the user to review their address and either confirm it is correct or fix and revalidate it before proceeding. STOP: The calling application should prevent the user from proceeding until they fix and revalidate the address. " } } }, "validGeographicAddress": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique Place Id for the address" }, "streetNumber": { "type": "string", "description": "Number identifying a specific property on a public street. It may be combined with streetNrLast for ranged addresses" }, "streetName": { "type": "string", "description": "Name of the street or other street type" }, "streetType": { "type": "string", "description": "alley, avenue, boulevard, brae, crescent, drive, highway, lane, terrace, parade, place, tarn, way, wharf " }, "streetSuffix": { "type": "string", "description": "A modifier denoting a relative direction" }, "city": { "type": "string", "description": "City that the address is in" }, "stateOrProvince": { "type": "string", "description": "the State or Province that the address is in" }, "country": { "type": "string", "description": "Country that the address is in" }, "postalcode": { "type": "string", "description": "descriptor for a postal delivery area, used to speed and simplify the delivery of mail (also know as zipcode)" }, "postalcodeExtension": { "type": "string", "description": "4 digit extension of the zipcode" }, "geographicSubAddress": { "type": "array", "items": { "$ref": "#/components/schemas/GeographicSubAddress" } }, "addressCharacteristic": { "type": "array", "items": { "$ref": "#/components/schemas/AddressCharacteristic" } } }, "description": "Populated with the address details if address is valid and there is an exact match identified" }, "AlternateGeographicAddress": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique Place Id for the address" }, "streetNumber": { "type": "string", "description": "Number identifying a specific property on a public street. It may be combined with streetNrLast for ranged addresses" }, "streetName": { "type": "string", "description": "Name of the street or other street type" }, "streetType": { "type": "string", "description": "alley, avenue, boulevard, brae, crescent, drive, highway, lane, terrace, parade, place, tarn, way, wharf " }, "streetSuffix": { "type": "string", "description": "A modifier denoting a relative direction" }, "city": { "type": "string", "description": "City that the address is in" }, "stateOrProvince": { "type": "string", "description": "the State or Province that the address is in" }, "country": { "type": "string", "description": "Country that the address is in" }, "postalcode": { "type": "string", "description": "descriptor for a postal delivery area, used to speed and simplify the delivery of mail (also know as zipcode)" }, "postalcodeExtension": { "type": "string", "description": "4 digit extension of the zipcode" }, "geographicSubAddress": { "type": "array", "items": { "$ref": "#/components/schemas/GeographicSubAddress" } }, "addressCharacteristic": { "type": "array", "items": { "$ref": "#/components/schemas/AddressCharacteristic" } } } }, "GeographicSubAddress": { "type": "object", "properties": { "buildingName": { "type": "string", "description": "allows for buildings that have well-known names" }, "levelNumber": { "type": "string", "description": "used where a level type may be repeated e.g. BASEMENT 1, BASEMENT 2" }, "levelType": { "type": "string", "description": "describes level types within a building" }, "subUnitNumber": { "type": "string", "description": "the discriminator used for the subunit\noften just a simple number e.g. FLAT 5, may also be a range" }, "subUnitType": { "type": "string", "description": "the type of subunit\ne.g.BERTH, FLAT, PIER, SUITE, SHOP, TOWER, UNIT, WHARF" }, "structureType": { "type": "string", "description": "Type of the Structure" }, "structureValue": { "type": "string", "description": "Structure value" }, "subAddressType": { "type": "string", "description": "The first character indicates the type of address: F = Firm (not foreign). G = General delivery. H = High-rise apartment or office building. M = Military. P = Post office box. R = Rural route or highway contract. S = Street (usually, one side of one city block). blank Unassigned. The second character may be a D or blank. The D stands for default; it means that a more precise postalCodePlus4 (zip4) could have been assigned if more information had been provided. FD = Firm default. A firm-level zip4 was not assigned but could have been if given more or better firm information. GD = General delivery default. Assigned only when General Delivery is the only primary name listed for the zip code. HD = High-rise default. The zip4 for the whole building was assigned. Assignment at the unit, floor, or wing level is possible. Often caused by a suite or apartment number out of range. RD = Rural route or highway contract default. The zip4 for the whole route was assigned; could do better with box number. SD = Street default. Usually means that there is no zip4 for the building, so the transform had to assign the zip4 for the block. UD = Unique default. Either the owner of the unique zip code has not provided zip4 assignments, or the address could not be matched." } }, "description": "Representation of a GeographicSubAddress\nIt is used for addressing within a property in an urban area (country properties are often defined differently). It may refer to a building, a building cluster, or a floor of a multistory building." }, "AddressCharacteristic": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of address characteristic." }, "value": { "type": "string", "description": "Value of address characteristic." } }, "description": "Representation of a GeographicSubAddress\nIt is used for addressing within a property in an urban area (country properties are often defined differently). It may refer to a building, a building cluster, or a floor of a multistory building." }, "Error": { "type": "object", "properties": { "errorCode": { "type": "string", "example": "<400-INVALID-REQUEST>" }, "errorDescription": { "type": "string", "example": "Validation Failure" }, "errorList": { "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string", "example": "customer" }, "errorCode": { "type": "string", "example": "AUTH-142" }, "errorDescription": { "type": "string", "example": "" }, "errorDetails": { "type": "array", "items": { "type": "object", "properties": { "system": { "type": "string", "example": "IDGRAPH" }, "errorCode": { "type": "string", "example": "IDG-1235" }, "errorDescription": { "type": "string", "example": "" } } } } } } } } }, "Validation": { "type": "object", "properties": { "status": { "type": "string", "description": "Status of the order" }, "readyToSubmit": { "type": "boolean", "description": "Indicates if the order is ready to submit" }, "validationMessage": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "Validation message text" }, "type": { "type": "string", "description": "Component type" }, "parameter": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Holds the value for any line level error ids" }, "value": { "type": "string", "description": "Value of the parameter name" } } } } } } } } } } } }