{ "openapi": "3.1.2", "info": { "version": "1.0.0", "title": "Customer Search", "description": "This is an OpenAPI Specification for APIs that provide unified customer identity and account search.", "contact": { "name": "Omni API Support", "email": "DL-OmniAdapter@att.com" } }, "servers": [ { "url": "https://partner.att.com/omni-svcs" } ], "security": [], "tags": [ { "name": "Customer Search", "description": "Omni Customer Search" } ], "paths": { "/v1/customers/search": { "post": { "tags": [ "Customer Search" ], "description": "Returns Customers associated individuals, and account information.", "summary": "Search customers by identity and account attributes", "operationId": "CustomerSearch", "parameters": [ { "$ref": "#/components/parameters/ParameterAppname" } ], "requestBody": { "description": "Customer search request payload", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerSearchRequest" }, "examples": { "searchAfterAuthentication": { "summary": "Search after authentication", "x-tags": [ "Fiber-Move-Consumer", "Fiber-Change-Consumer" ], "value": { "serviceType": "FIBER", "pageSize": 5, "pageOffset": 1 } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerSearchResponse" }, "examples": { "fibercustomerAuthenticatedResponse": { "summary": "Customer search response with all individual fields", "x-tags": [ "Fiber-Move-Consumer", "Fiber-Change-Consumer" ], "value": { "totalCount": 1, "pageInfo": { "pageSize": 5, "pageOffset": 1 }, "individuals": [ { "id": "7ad6d9b1-1f26-4b7f-a76f-013b1b2d55de", "givenName": "JANE", "familyName": "DOE", "preferredName": "JANIE", "profile": { "firstName": "JANE", "lastName": "DOE", "middleInitial": "A" }, "status": "ACTIVE", "createdOn": "2025-01-10T09:00:00Z", "updatedOn": "2026-02-15T11:25:00Z", "accounts": [ { "id": "123456789", "givenName": "JANE", "familyName": "DOE", "title": "Ms", "middleInitial": "A", "accountType": "Consumer", "accountSubType": "Consumer Small Office", "ratingType": "STANDARD", "serviceType": "FIBER", "targetSOR": "LS-CRM-DB", "subscribersCount": "1", "createdOn": "2024-06-01T12:00:00Z", "lastModified": "2026-02-20T08:30:00Z", "openDate": "2024-06-02T00:00:00Z", "billingMarket": "DAL", "billingSubMarket": "DAL-NORTH", "accountLocked": "N", "state": { "state": "ACTIVE" }, "isDigitalAccount": true, "languagePreference": "en", "smbContactInfo": { "nameInfo": { "firstName": "JANE", "lastName": "DOE" } }, "subscribers": [ { "id": "SUB-10001", "phoneNumber": "**********", "createdOn": "2024-06-02T00:00:00Z", "updatedOn": "2026-02-19T10:10:00Z", "activationDate": "2024-06-02T00:00:00Z", "effectiveDate": "2026-02-19T10:10:00Z", "subMarket": "DAL-NORTH", "status": { "state": "ACTIVE" }, "products": [ { "productOfferingTypeGroup": "BBOffer", "isBundle": false, "productOfferingClassification": "FIBER_PLAN", "name": "AT&T Internet 1000", "description": "1 GIG speed + unlimited internet data", "status": { "status": "ACTIVE" }, "activationDate": "2024-06-02T00:00:00Z", "creationDate": "2024-06-01T12:00:00Z", "lastUpdate": "2026-02-19T10:10:00Z", "place": [ { "id": "ADDR-01" } ], "productCharacteristic": [ { "name": "downloadSpeed", "value": "1000 Mbps" }, { "name": "usageAllowance", "value": "Unlimited" } ] } ] } ] } ] } ] } } } } } }, "400": { "description": "Bad request - Missing fields, Invalid input data, validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WrappedPartnerServiceError" }, "examples": { "MissingSearchParameters": { "summary": "Missing search parameters", "value": { "error": { "errorId": "EXT_CUSTOMER_SEARCH-CG-0001", "message": "No search parameters provided. At least one search parameter combination must be supplied in the request.", "errorSystemId": "extpartnercustmgmtms", "details": [ { "code": "MISSING_SEARCHPARAMETERS", "message": "At least one search parameter combination must be provided." } ] } } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WrappedPartnerServiceError" }, "examples": { "CustomerSearchSystemError": { "summary": "System Error", "value": { "error": { "errorId": "EXT_CUSTOMER_SEARCH-CG-500", "message": "System Error", "errorSystemId": "Customer Search", "details": [ { "code": "INTERNAL_SERVER", "message": "Unexpected server error occurred during processing. Please try again later." } ] } } } } } } } } } } }, "components": { "schemas": { "CustomerSearchRequest": { "type": "object", "description": "Search criteria to filter individuals and associated accounts.", "properties": { "accountId": { "type": "string", "description": "Unique billing account identifier (BAN or account number)." }, "firstName": { "type": "string", "description": "Customer first name." }, "lastName": { "type": "string", "description": "Customer last name." }, "phoneNumber": { "type": "string", "description": "Customer contact number, CTN, or CBR." }, "emailAddress": { "type": "string", "description": "Customer email address." }, "serviceType": { "$ref": "#/components/schemas/ServiceType", "description": "Type of service associated with the customer." }, "pageSize": { "type": "integer", "format": "int32", "description": "Number of results to return per page.", "default": 5, "minimum": 1 }, "pageOffset": { "type": "integer", "format": "int32", "description": "Offset for pagination. Starts at 1.", "default": 1, "minimum": 1 } } }, "CustomerSearchResponse": { "type": "object", "properties": { "individuals": { "type": "array", "items": { "$ref": "#/components/schemas/Individual" } }, "pageInfo": { "$ref": "#/components/schemas/PageInfo" }, "totalCount": { "type": "integer", "format": "int32" } } }, "PageInfo": { "type": "object", "properties": { "pageSize": { "type": "integer", "format": "int32" }, "pageOffset": { "type": "integer", "format": "int32" } } }, "Individual": { "type": "object", "properties": { "id": { "type": "string" }, "givenName": { "type": "string" }, "familyName": { "type": "string" }, "preferredName": { "type": "string" }, "relatedAccounts": { "type": "array", "items": { "$ref": "#/components/schemas/RelatedAccount" } }, "profile": { "$ref": "#/components/schemas/Profile" }, "status": { "type": "string" }, "createdOn": { "type": "string", "format": "date-time" }, "updatedOn": { "type": "string", "format": "date-time" }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/Account" } } } }, "RelatedAccount": { "type": "object", "properties": { "accountId": { "type": "string" }, "role": { "type": "string" }, "customerId": { "type": "string" } } }, "Profile": { "type": "object", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "middleInitial": { "type": "string" }, "emailAddress": { "type": "string" }, "phoneNumber": { "type": "string" } } }, "ServiceType": { "type": "string", "enum": [ "WIRELESS", "UVERSE", "WIRELESSBROADBAND", "FIBER" ] }, "ProductCustomerSearch": { "type": "object", "description": "Product resource for unified customer search.", "properties": { "productOfferingTypeGroup": { "type": "string", "description": "Product offering type group." }, "id": { "type": "string", "description": "Unique product identifier." }, "isBundle": { "type": "boolean", "description": "Indicates whether the product is a bundle." }, "productOfferingClassification": { "type": "string", "description": "Product offering classification." }, "rootProductId": { "type": "string", "description": "Root product identifier." }, "productOfferingId": { "type": "string", "description": "Product offering identifier." }, "name": { "type": "string", "description": "Product name." }, "productCode": { "type": "string", "description": "Product code." }, "description": { "type": "string", "description": "Product description." }, "status": { "type": "object", "description": "Current product status details.", "additionalProperties": true }, "place": { "type": "array", "description": "Places associated with the product.", "items": { "type": "object", "additionalProperties": true } }, "productCharacteristic": { "type": "array", "description": "Characteristics associated with the product.", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": true }, "Subscriber": { "type": "object", "description": "Subscriber resource for unified customer search.", "properties": { "id": { "type": "string", "description": "Unique subscriber identifier." }, "phoneNumber": { "type": "string", "description": "Subscriber phone number (CTN/MSISDN)." }, "createdOn": { "type": "string", "format": "date-time", "description": "Timestamp when the subscriber record was created." }, "updatedOn": { "type": "string", "format": "date-time", "description": "Timestamp when the subscriber record was last updated." }, "activationDate": { "type": "string", "format": "date-time", "description": "Subscriber activation date and time." }, "effectiveDate": { "type": "string", "format": "date-time", "description": "Effective date and time for current subscriber state." }, "subMarket": { "type": "string", "description": "Subscriber submarket code." }, "status": { "type": "object", "description": "Subscriber status details.", "properties": { "state": { "type": "string", "description": "Current lifecycle state value." }, "stateChangeReason": { "type": "array", "description": "History of reasons associated with subscriber state transitions.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Reason name." }, "date": { "type": "string", "format": "date-time", "description": "Timestamp when the reason was recorded." }, "description": { "type": "string", "description": "Reason description." } } } } } }, "products": { "type": "array", "description": "Products associated with the subscriber.", "items": { "$ref": "#/components/schemas/ProductCustomerSearch" } } } }, "Account": { "type": "object", "description": "Account resource for unified customer search.", "properties": { "id": { "type": "string", "description": "Unique account identifier." }, "givenName": { "type": "string", "description": "Given name of the account holder." }, "familyName": { "type": "string", "description": "Family name of the account holder." }, "title": { "type": "string", "description": "Title of the account holder (for example, Mr, Ms, or Dr)." }, "middleInitial": { "type": "string", "description": "Middle initial of the account holder." }, "accountType": { "type": "string", "description": "Primary account type classification." }, "accountSubType": { "type": "string", "description": "Secondary account type classification." }, "ratingType": { "type": "string", "description": "Rating category used for billing and charging." }, "serviceType": { "type": "string", "description": "Line-of-business service type (for example, wireless, fiber, or U-verse)." }, "targetSOR": { "type": "string", "description": "Target SOR (System of Record) for this account." }, "subscribersCount": { "type": "string", "description": "Number of subscribers linked to the account, represented as a source string." }, "createdOn": { "type": "string", "format": "date-time", "description": "Timestamp when the account record was created." }, "lastModified": { "type": "string", "format": "date-time", "description": "Timestamp when the account record was last modified." }, "openDate": { "type": "string", "format": "date-time", "description": "Date and time when the account became active." }, "billingMarket": { "type": "string", "description": "Billing market code for the account." }, "billingSubMarket": { "type": "string", "description": "Billing submarket code for the account." }, "accountLocked": { "type": "string", "description": "Indicates whether the account is locked and, if applicable, the lock state." }, "state": { "type": "object", "description": "Lifecycle state information for the account.", "properties": { "state": { "type": "string", "description": "Current lifecycle state value." }, "stateChangeReason": { "type": "array", "description": "History of reasons associated with account state transitions.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Reason name." }, "date": { "type": "string", "format": "date-time", "description": "Timestamp when the reason was recorded." }, "description": { "type": "string", "description": "Reason description." }, "activity": { "type": "string", "description": "Associated activity that triggered the state change." } }, "additionalProperties": true } } }, "additionalProperties": true }, "isDigitalAccount": { "type": "boolean", "description": "Indicates whether this account is marked as digital." }, "languagePreference": { "type": "string", "description": "Preferred language for account communications." }, "smbContactInfo": { "type": "object", "description": "SMB (Small and Medium Business) contact details.", "additionalProperties": true }, "subscribers": { "description": "List of subscribers associated with this account.", "type": "array", "items": { "$ref": "#/components/schemas/Subscriber" } } } }, "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" } } } }