{ "openapi": "3.1.2", "info": { "version": "1.0.2", "title": "extpartneromnisvcsms", "description": "This is an OpenAPI Specification for 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" } ], "security": [], "tags": [ { "name": "Address Validation", "description": "APIs for Address Validation" } ], "paths": { "/v1/address/validate": { "post": { "tags": [ "Address Validation" ], "description": "The Validate Address endpoint offers real-time verification and normalization of customer postal addresses.\n It ensures that address data conforms to AT&T’s internal standards and third-party reference (e.g. USPS) before downstream use in ordering, service eligibility checks, billing, or fulfillment. \nAddress Supported are PPU, Billing, Shipping. \n\n Key Benefits: \n\n 1. Reduces delivery failures and billing errors by catching bad addresses early. \n\n 2. Streamlines customer onboarding flows for Apple, SaraPlus, and other national retail partners. \n\n 3. Supports AT&T’s MVPD and broadband services with a single, standards-based interface.", "summary": "Perform Address Validation", "operationId": "validateAddress", "parameters": [ { "$ref": "#/components/parameters/ParameterAppname" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressValidationRequest" }, "examples": { "Address_Validation_With AddressLine2_Fiber": { "x-tags": [ "Fiber-Provide-Consumer", "Fiber-Move-Consumer", "Fiber-Change-Consumer" ], "value": { "addressLine1": "23114 38th Ave SE", "addressLine2": "APT 123", "addressType": "Shipping, Billing", "productCategory": "Fiber", "city": "CHOLA VISTA", "zipCode": "98021", "stateOrProvince": "WA" } }, "Address_Validation_Close_Match_Fiber": { "x-tags": [ "Fiber-Provide-Consumer", "Fiber-Move-Consumer", "Fiber-Change-Consumer" ], "value": { "addressLine1": "3400 w plano pkwu", "addressType": "PPU", "productCategory": "Fiber", "zipCode": "75075", "city": "Plano", "stateOrProvince": "TX" } } } } } }, "responses": { "200": { "description": "Address validation response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressValidationResponse" }, "examples": { "Success_Response": { "x-tags": [ "Wireless", "Fiber-Provide-Consumer", "Fiber-Move-Consumer", "Fiber-Change-Consumer" ], "value": { "validationResult": "success", "validationResultCode": "4S80", "validGeographicAddress": { "id": "00000NG3XH", "streetNumber": "3802", "streetName": "MAIN", "streetType": "ST", "city": "CHULA VISTA", "stateOrProvince": "CA", "zipCode": "91911", "zipCodeExt": "6247", "geographicSubAddress": [ { "subUnitType": "STE", "subUnitNumber": "5", "subAddressType": "H" } ], "addressCharacteristic": [ { "addressLine1": "3802 MAIN ST STE 5", "city": "CHULA VISTA", "county": "cook" } ] }, "validationTypeRecommendation": [ { "validationType": "BILLING", "validationRecommendation": "ACCEPT" }, { "validationType": "SHIPPING", "validationRecommendation": "ACCEPT" } ] } }, "Close_Match_Multiple_Matches_Response": { "x-tags": [ "Wireless", "Fiber-Provide-Consumer", "Fiber-Move-Consumer", "Fiber-Change-Consumer" ], "value": { "validationResult": "closematch", "validationResultCode": "Multiple", "validationResultDescription": "Address validation found multiple matches", "alternateGeographicAddress": [ { "city": "PLANO", "stateOrProvince": "TX", "zipCode": "75075", "zipCodeExt": "8011", "addressCharacteristic": [ { "addressLine1": "3400 W PLANO PKWY", "addressLine2": "", "city": "PLANO", "county": "collin" } ] }, { "city": "PLANO", "stateOrProvince": "TX", "zipCode": "75075", "zipCodeExt": "7203", "addressCharacteristic": [ { "addressLine1": "3400 W PLANO PKWY", "county": "collin" } ] } ], "validationTypeRecommendation": [ { "validationType": "PPU", "validationRecommendation": "ACCEPT" } ] } }, "Partial_Match_with_Recommendation_Response": { "x-tags": [ "Wireless", "Fiber-Provide-Consumer", "Fiber-Move-Consumer", "Fiber-Change-Consumer" ], "value": { "validationResult": "closematch-mdu", "validationResultCode": "3SMU", "validationResultDescription": "Address is missing unit information. Mail may not be delivered", "alternateGeographicAddress": [ { "city": "HOUSTON", "stateOrProvince": "TX", "zipCode": "77077", "zipCodeExt": "7601", "addressCharacteristic": [ { "addressLine1": "2400 BRIARWEST BLVD", "addressLine2": "", "city": "HOUSTON", "county": "cook" } ], "geographicSubAddress": [ { "subUnitType": "APT", "subUnitNumber": "2209" } ] }, { "city": "HOUSTON", "stateOrProvince": "TX", "zipCode": "77077", "zipCodeExt": "7601", "addressCharacteristic": [ { "addressLine1": "2400 BRIARWEST BLVD", "county": "cook" } ], "geographicSubAddress": [ { "subUnitType": "APT", "subUnitNumber": "2317" } ] } ], "validationTypeRecommendation": [ { "validationType": "PPU", "validationRecommendation": "STOP" } ] } }, "No_Match_Response": { "x-tags": [ "Wireless", "Fiber-Provide-Consumer", "Fiber-Move-Consumer", "Fiber-Change-Consumer" ], "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 - Missing fields, Invalid input data, validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WrappedPartnerServiceError" }, "examples": { "InvalidAddressType": { "summary": "Invalid Address Type", "value": { "error": { "errorId": "EXT_OMNI_SVC-GA-V100017", "message": "AddressType is invalid", "errorSystemId": "GeoAddress", "details": [ { "code": "GA-V100017", "message": "Invalid Address Type" } ] } } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WrappedPartnerServiceError" }, "examples": { "AddressValidationSystemError": { "summary": "System Error", "value": { "error": { "errorId": "EXTOMNISVCS_VALID_ADDRESS_GEO-0003", "message": "Downstream service error occurred for address validation", "errorSystemId": "GeoAddress", "details": [ { "code": "GA-B40000", "message": "Could not reach downstream system" } ] } } } } } } } } } } }, "components": { "schemas": { "AddressValidationRequest": { "type": "object", "properties": { "addressLine1": { "type": "string", "description": "First line of the address including street number, street name, and street type" }, "addressLine2": { "type": "string", "description": "Second line of the address for apartment, suite, unit, or building information" }, "addressType": { "type": "string", "description": "Type of address validation required. Valid values are Billing, Shipping, or PPU (Point of Presence). Allows multiple values separated by comma" }, "productCategory": { "type": "string", "description": "Product category for address validation (e.g., WSS for wireless, WBB for wireline broadband, Fiber)" }, "city": { "type": "string", "description": "City that the address is in" }, "zipCode": { "type": "string", "description": "Descriptor for a postal delivery area, used to speed and simplify the delivery of mail (also known as ZIP code)" }, "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)" }, "AddressValidationResponse": { "type": "object", "properties": { "validationResult": { "type": "string", "description": "Result of the address validation. Possible values: success (exact match found), closematch (multiple matches found), closematch-mdu (Multiple Dwelling Unit address requiring unit information), nomatch (no match found), fails (validation failed)" }, "validationResultCode": { "type": "string", "description": "Address match code indicating the quality and type of match" }, "validationResultDescription": { "type": "string", "description": "Detailed description for the validation result code" }, "validGeographicAddress": { "$ref": "#/components/schemas/validGeographicAddress" }, "alternateGeographicAddress": { "type": "array", "items": { "$ref": "#/components/schemas/AlternateGeographicAddress" }, "description": "List of alternate addresses when multiple matches are found or for Multiple Dwelling Units (MDU) requiring additional selection" }, "validationTypeRecommendation": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationTypeRecommendation" }, "description": "Recommended actions for each address validation type based on the validation results" } }, "description": "This resource is used to manage address validation response", "title": "" }, "ValidationTypeRecommendation": { "type": "object", "properties": { "validationType": { "type": "string", "description": "Type of address validation. BILLING: Billing address validation, SHIPPING: Shipping address validation, PPU: Point of Presence validation", "enum": [ "BILLING", "SHIPPING", "PPU" ] }, "validationRecommendation": { "type": "string", "enum": [ "ACCEPT", "LIST", "WARN", "STOP" ], "description": "Recommended action based on validation results. ACCEPT: Allow the user to proceed with the validated address. LIST: Present the list of returned addresses and allow the user to select one or enter a different address for validation. WARN: Require the user to review and confirm the address is correct or fix and revalidate before proceeding. STOP: 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": "Type of the street. Alley, avenue, boulevard, brae, crescent, drive, highway, lane, terrace, parade, place, tarn, way, wharf" }, "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" }, "zipCode": { "type": "string", "description": "Descriptor for a postal delivery area, used to speed and simplify the delivery of mail (also known as ZIP code)" }, "zipCodeExt": { "type": "string", "description": "Four-digit extension of the ZIP code (ZIP+4)" }, "geographicSubAddress": { "type": "array", "description": "Sub-address information for units within a property (e.g., apartment, suite, floor)", "items": { "$ref": "#/components/schemas/GeographicSubAddress" } }, "addressCharacteristic": { "type": "array", "description": "Additional address characteristic information", "items": { "$ref": "#/components/schemas/AddressCharacteristicGeo" } } }, "description": "Geographic address details populated when address is valid and an exact match is 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": "Type of the street. Examples: Alley, Avenue, Boulevard, Brae, Crescent, Drive, Highway, Lane, Terrace, Parade, Place, Tarn, Way, Wharf" }, "streetSuffix": { "type": "string", "description": "Street suffix indicating a directional or positional modifier (e.g., N, S, E, W, NE, SW)" }, "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" }, "zipCode": { "type": "string", "description": "Descriptor for a postal delivery area, used to speed and simplify the delivery of mail (also known as ZIP code)" }, "zipCodeExt": { "type": "string", "description": "Four-digit extension of the ZIP code (ZIP+4)" }, "geographicSubAddress": { "type": "array", "description": "Sub-address information for units within a property (e.g., apartment, suite, floor)", "items": { "$ref": "#/components/schemas/GeographicSubAddress" } }, "addressCharacteristic": { "type": "array", "description": "Additional address characteristic information", "items": { "$ref": "#/components/schemas/AddressCharacteristicGeo" } } }, "description": "Alternate geographic address when multiple matches are found or for Multiple Dwelling Units" }, "GeographicSubAddress": { "type": "object", "properties": { "buildingName": { "type": "string", "description": "Name for buildings that have well-known names" }, "levelNumber": { "type": "string", "description": "Level number used where a level type may be repeated (e.g., BASEMENT 1, BASEMENT 2)" }, "levelType": { "type": "string", "description": "Type of level within a building (e.g., Floor, Basement, Mezzanine)" }, "subUnitNumber": { "type": "string", "description": "Number or identifier for the sub-unit. Often a simple number (e.g., FLAT 5), may also be a range" }, "subUnitType": { "type": "string", "description": "Type of sub-unit. Examples: BERTH, FLAT, PIER, SUITE, SHOP, TOWER, UNIT, WHARF" }, "structureType": { "type": "string", "description": "Type of structure (e.g., BLDG for building)" }, "structureValue": { "type": "string", "description": "Value or identifier of the structure (e.g., Building 1, Building A)" }, "subAddressType": { "type": "string", "description": "Type of sub-address. First character indicates address type: F=Firm, G=General delivery, H=High-rise building, M=Military, P=Post office box, R=Rural route, S=Street, blank=Unassigned. Second character may be D (default) indicating a more precise ZIP+4 could have been assigned with more information. Examples: FD=Firm default, GD=General delivery default, HD=High-rise default, RD=Rural route default, SD=Street default, UD=Unique default" } }, "description": "Sub-address information used for addressing within a property in an urban area (country properties are often defined differently). May refer to a building, building cluster, or floor of a multistory building" }, "AddressCharacteristicGeo": { "type": "object", "properties": { "addressLine1": { "type": "string", "description": "Complete first line of the address including street number, street name, street type, and any applicable sub-unit information" }, "addressLine2": { "type": "string", "description": "Complete second line of the address for additional location information" }, "city": { "type": "string", "description": "City name of the address" }, "county": { "type": "string", "description": "County name where the address is located" } }, "description": "Additional characteristics of the validated geographic address providing formatted address lines and location details" }, "PartnerServiceError": { "type": "object", "properties": { "errorId": { "type": "string", "example": "Top level error code" }, "message": { "type": "string", "example": "Top level error message" }, "errorSystemId": { "type": "string", "example": "System name" }, "details": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "Detail code 1" }, "message": { "type": "string", "example": "Detail message 1" } } } } } }, "WrappedPartnerServiceError": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/PartnerServiceError" } } } }, "parameters": { "ParameterAppname": { "name": "appname", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Application name making the request" } } } }