Vendasta Listing Products Service API

openapi: 3.2.0
info:
  title: Listing Products Service API
  version: 1.210.0
servers:
- description: Production
  url: https://prod.apigateway.co/grpc
tags:
- name: ListingProductsService
paths:
  /v1/listings/get-sync-data:
    post:
      operationId: ListingProductsService_GetSyncData
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/v1GetSyncDataRequest'
        description: Request to retrieve comprehensive sync status and listing accuracy data for a business across all directory sources.
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1GetSyncDataResponse'
          description: A successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
          description: An unexpected error response.
      security:
      - OAuth2:
        - business-app
      summary: Get Sync Data
      tags:
      - ListingProductsService
components:
  schemas:
    rpcStatus:
      properties:
        code:
          format: int32
          type: integer
        details:
          items:
            $ref: '#/components/schemas/protobufAny'
          type: array
        message:
          type: string
      type: object
    v1SourceAccuracy:
      properties:
        anchorData:
          $ref: '#/components/schemas/v1AnchorData'
        anchorDataMatches:
          $ref: '#/components/schemas/v1AnchorDataMatches'
        lastScraped:
          format: date-time
          title: 'last_scraped is when we last checked the directory''s live listing

            If this is old, the accuracy data might be stale (we scrape periodically, not real-time)'
          type: string
        status:
          $ref: '#/components/schemas/v1AccuracyStatus'
      title: 'SourceAccuracy contains comprehensive accuracy information for a listing on a directory.

        This shows both the expected data and field-by-field comparison with what''s actually live.

        This is the key data structure for answering "why is my listing inaccurate?"'
      type: object
    v1Metadata:
      description: 'Metadata contains additional key-value information about a sync.

        Contents vary by directory - may include submission IDs, provider-specific status codes, etc.'
      properties:
        key:
          title: key is the metadata field name
          type: string
        value:
          title: value is the metadata field value
          type: string
      type: object
    v1DetailedSyndicationStatusResults:
      properties:
        key:
          title: key identifies the data type category (e.g., "location" for NAP data, "hours" for business hours, "photos" for images)
          type: string
        value:
          $ref: '#/components/schemas/v1DetailedSyndicationStatusResultValue'
      title: 'DetailedSyndicationStatusResults provides granular sync status for different data types within a sync.

        Key-value pairs where key is the data type (e.g., "location", "hours", "photos")'
      type: object
    v1SyncRequirement:
      default: SYNC_REQUIREMENT_UNSET
      description: "SyncRequirement specifies what product activation is needed to automatically sync to a directory.\nThis explains why a directory might not be available for a particular business.\n\n - SYNC_REQUIREMENT_UNSET: SYNC_REQUIREMENT_UNSET means no specific requirement (e.g., manual submission via RM, or direct OAuth)\n - SYNC_REQUIREMENT_LSP: SYNC_REQUIREMENT_LSP requires an active Listing Sync Pro subscription (either Yext or Uberall)\n - SYNC_REQUIREMENT_PRO_EDITION: SYNC_REQUIREMENT_PRO_EDITION requires Local SEO Pro edition\n - SYNC_REQUIREMENT_YEXT_LSP: SYNC_REQUIREMENT_YEXT_LSP specifically requires Yext-based Listing Sync Pro\nThis directory is only available through Yext, not Uberall\n - SYNC_REQUIREMENT_UBERALL_LSP: SYNC_REQUIREMENT_UBERALL_LSP specifically requires Uberall-based Listing Sync Pro\nThis directory is only available through Uberall, not Yext\n - SYNC_REQUIREMENT_LSP_OR_PRO_EDITION: SYNC_REQUIREMENT_LSP_OR_PRO_EDITION requires either Listing Sync Pro OR Local SEO Pro"
      enum:
      - SYNC_REQUIREMENT_UNSET
      - SYNC_REQUIREMENT_LSP
      - SYNC_REQUIREMENT_PRO_EDITION
      - SYNC_REQUIREMENT_YEXT_LSP
      - SYNC_REQUIREMENT_UBERALL_LSP
      - SYNC_REQUIREMENT_LSP_OR_PRO_EDITION
      type: string
    v1EcosystemSource:
      description: 'EcosystemSource represents a secondary directory that receives data when syncing to a primary aggregator.

        Example: When syncing to Neustar or Data Axle, data flows to dozens of downstream directories.'
      properties:
        icon:
          title: icon is the URL to the directory's logo/icon
          type: string
        name:
          title: name is the human-readable name of the downstream directory (e.g., "TomTom", "Garmin", "MapQuest")
          type: string
        sourceId:
          title: source_id is the numeric ID of the downstream directory
          type: string
      type: object
    protobufAny:
      additionalProperties: {}
      properties:
        '@type':
          type: string
      type: object
    v1AnchorData:
      description: 'AnchorData contains the expected business NAP (Name, Address, Phone) data from the business profile.

        This is the "source of truth" that we compare against what''s live on the directory to determine accuracy.'
      properties:
        address:
          title: address is the expected street address
          type: string
        city:
          title: city is the expected business city
          type: string
        companyName:
          title: company_name is the expected business name
          type: string
        country:
          title: country is the expected country code
          type: string
        phone:
          title: phone is the expected primary phone number
          type: string
        state:
          title: state is the expected state/province
          type: string
        website:
          title: website is the expected business website URL
          type: string
        zip:
          title: zip is the expected postal/zip code
          type: string
      type: object
    v1DetailedSyndicationStatusResultValue:
      description: 'DetailedSyndicationStatusResultValue contains field-level sync results for a specific data type.

        This shows exactly which fields synced successfully and which failed within a data category.'
      properties:
        dataType:
          title: data_type is the category of data (matches the key in parent message)
          type: string
        errorMessage:
          title: 'error_message contains the specific error for failed fields

            Example: "Phone number format invalid for Bing Places. Must be (XXX) XXX-XXXX"'
          type: string
        failedFields:
          items:
            type: string
          title: 'failed_fields lists individual fields that failed to sync

            Example: ["phone"] - this tells you exactly which field is causing the problem'
          type: array
        lastSyncTime:
          format: date-time
          title: last_sync_time is when this data type was last synced successfully
          type: string
        status:
          title: status is the high-level status for this data type ("success", "failed", "partial")
          type: string
        syncedFields:
          items:
            type: string
          title: 'synced_fields lists individual fields that synced successfully

            Example: ["company_name", "address", "city", "state", "zip"]'
          type: array
      type: object
    v1SyndicationStatus:
      description: 'SyndicationStatus contains detailed sync execution information for a directory.

        This provides the forensic details needed to diagnose why a sync failed or is taking longer than expected.'
      properties:
        detailedResults:
          items:
            $ref: '#/components/schemas/v1DetailedSyndicationStatusResults'
          title: 'detailed_results contains field-by-field sync results showing which fields succeeded and which failed

            Critical for answering "why did only some of my fields sync?"'
          type: array
        lastAttemptedOn:
          format: date-time
          readOnly: true
          title: 'Output only. When the most recent sync attempt started (successful or failed).

            Use this to determine "when did we last try to sync?"'
          type: string
        lastSucceededOn:
          description: 'Output only. When the most recent successful sync completed.

            If this is significantly older than last_attempted_on, syncs are failing.'
          format: date-time
          readOnly: true
          type: string
        lastSuccessfulAttemptId:
          title: last_successful_attempt_id is the workflow execution ID for the most recent successful sync (for debugging)
          type: string
        lastSyncAttemptId:
          title: last_sync_attempt_id is the workflow execution ID for the most recent sync attempt (for debugging)
          type: string
        listingExternalId:
          title: listing_external_id is the directory's internal ID for this listing (e.g., Google Place ID, Yelp Business ID)
          type: string
        listingUrl:
          title: listing_url is the public URL where this listing can be viewed on the directory
          type: string
        metadata:
          items:
            $ref: '#/components/schemas/v1Metadata'
          title: metadata contains additional key-value pairs with sync-specific information
          type: array
        status:
          title: status is a human-readable status message (may contain error details)
          type: string
        updated:
          description: Output only. When this sync status was last modified.
          format: date-time
          readOnly: true
          type: string
      type: object
    v1ConnectedDirectSyncAccount:
      description: 'ConnectedDirectSyncAccount represents an OAuth-connected account for direct sync sources (Google, Facebook, Apple, Bing).

        This is only populated for directories that require OAuth authentication to sync.'
      properties:
        accountId:
          title: account_id is the directory's internal identifier for this account (e.g., Google Account ID, Facebook Page ID)
          type: string
        accountType:
          title: account_type identifies the directory/service type (e.g., "google", "facebook", "apple", "bing")
          type: string
        clientTags:
          items:
            type: string
          title: client_tags are partner-specific tags associated with this account
          type: array
        connectionId:
          title: connection_id uniquely identifies this connection in the Core Services system (also known as Social Service ID)
          type: string
        disabledFlag:
          title: disabled_flag indicates this connection has been manually disabled and cannot be used
          type: boolean
        isAuthenticated:
          title: 'is_authenticated indicates if the OAuth token is valid and the account is currently connected

            False means the user needs to re-authenticate (token expired or was revoked)'
          type: boolean
        isSyncingEnabled:
          title: 'is_syncing_enabled indicates if automatic syncing is turned on for this specific account

            A business might have multiple Google accounts connected but only sync to one'
          type: boolean
        isVerified:
          title: 'is_verified indicates the account has been verified/claimed by the provider

            Example: a verified Google Business Profile location vs. an unverified one'
          type: boolean
        profileImageUrl:
          title: profile_image_url is the avatar/logo URL for the connected account
          type: string
        profileUrl:
          title: profile_url is the URL to the account's profile page on the directory (e.g., Google Business Profile dashboard)
          type: string
        tokenBroken:
          title: 'token_broken indicates the OAuth token is invalid, expired, or revoked

            User action required: Reconnect the account to get a fresh OAuth token'
          type: boolean
        username:
          title: username is the display name or email of the connected account (e.g., "john@example.com" for Google)
          type: string
      type: object
    v1GetSyncDataRequest:
      description: Request to retrieve comprehensive sync status and listing accuracy data for a business across all directory sources.
      properties:
        businessId:
          description: Required. The business ID (also known as account_group_id) uniquely identifying the business location.
          type: string
        includeHidden:
          description: 'Optional. Returns directories that are normally hidden from the UI (e.g., disabled by partner, not applicable to business category).

            Set to true for comprehensive troubleshooting or to see all possible directories.'
          type: boolean
        refresh:
          description: 'Optional. Forces a refresh of OAuth tokens for connected accounts (Google, Facebook, etc.).

            Set to true if you suspect authentication issues. This will add latency to the request.'
          type: boolean
        sourceIds:
          description: 'Optional. Filters results to only include specific directory IDs.

            If empty, returns all directories. Use this to check status of specific directories efficiently.'
          items:
            type: string
          type: array
      required:
      - businessId
      title: GetSyncDataRequest
      type: object
    v1SyncData:
      description: 'SyncData contains comprehensive sync status and accuracy information for a single directory source.

        This is the primary data structure for understanding listing presence, accuracy, and sync health.'
      properties:
        account:
          $ref: '#/components/schemas/v1ConnectedDirectSyncAccount'
        accuracy:
          $ref: '#/components/schemas/v1SourceAccuracy'
        additionalAccounts:
          items:
            $ref: '#/components/schemas/v1ConnectedDirectSyncAccount'
          title: 'additional_accounts lists other OAuth accounts connected for this directory that could be used for syncing

            Useful when a business has multiple Google accounts and needs to choose which one to sync to'
          type: array
        connectLink:
          title: connect_link is the URL to initiate OAuth connection for direct sync sources
          type: string
        ecosystemSources:
          items:
            $ref: '#/components/schemas/v1EcosystemSource'
          title: 'ecosystem_sources lists secondary directories that receive data when syncing to this primary directory

            Example: syncing to Neustar also syncs to dozens of downstream directories'
          type: array
        hidden:
          title: hidden indicates this directory is not shown in the UI (e.g., disabled by partner, not applicable to business category)
          type: boolean
        hiddenReason:
          title: hidden_reason explains why the directory is hidden (e.g., "Not available in your region", "Not compatible with your business category")
          type: string
        iconUrl:
          title: icon_url is the URL to the directory's logo/icon for display purposes
          type: string
        isListingVerified:
          title: is_listing_verified indicates the business owner has manually verified this listing as accurate
          type: boolean
        isSyncingEnabled:
          title: 'is_syncing_enabled indicates if automatic syncing is turned on for this directory

            False means changes to the business profile won''t propagate to this directory'
          type: boolean
        listingId:
          title: listing_id is the internal identifier for this listing in the Core Services system
          type: string
        listingUrl:
          title: 'listing_url is the public-facing URL where the listing can be viewed on the directory

            Empty if listing not found or claimed by someone else'
          type: string
        locked:
          title: locked indicates syncing cannot be enabled due to business constraints (e.g., missing required fields, account not eligible)
          type: boolean
        maxScore:
          format: int64
          title: max_score is the maximum possible score for this directory (usually 100, but varies by directory capabilities)
          type: string
        name:
          title: name is the human-readable directory name (e.g., "Google", "Yelp", "Facebook", "Bing Places")
          type: string
        provider:
          $ref: '#/components/schemas/v1Provider'
        requirement:
          $ref: '#/components/schemas/v1SyncRequirement'
        score:
          format: int64
          title: score is the current accuracy score (0-100) representing how complete and accurate this listing is
          type: string
        sourceId:
          title: source_id is the numeric ID uniquely identifying this directory (e.g., "1" for Google, "2" for Facebook)
          type: string
        sourceType:
          title: source_type categorizes the directory (e.g., "search_engine", "social_network", "review_site", "data_aggregator")
          type: string
        syncDetails:
          $ref: '#/components/schemas/v1SyndicationStatus'
        syncStatus:
          $ref: '#/components/schemas/v1SyncStatus'
      type: object
    v1SyncStatus:
      default: SYNC_STATUS_UNSET
      description: "SyncStatus represents the current state of syncing to a directory.\nThis is the high-level status that determines what action a user should take.\n\n - SYNC_STATUS_UNSET: SYNC_STATUS_UNSET means syncing has not been attempted or is not enabled for this directory.\nUser action: Enable syncing if they want this directory to be kept up to date.\n - SYNC_STATUS_SYNCING: SYNC_STATUS_SYNCING means a sync is currently in progress.\nUser action: Wait for sync to complete. Check sync_details for progress.\n - SYNC_STATUS_PARTIALLY_SYNCED: SYNC_STATUS_PARTIALLY_SYNCED means some fields synced successfully but others failed or have warnings.\nUser action: Review sync_details.detailed_results to see which fields failed and why.\n - SYNC_STATUS_SUCCESS: SYNC_STATUS_SUCCESS means the listing synced successfully and all fields are up to date.\nUser action: None required. Listing is healthy.\n - SYNC_STATUS_FAILED: SYNC_STATUS_FAILED means the sync attempt failed completely.\nUser action: Review sync_details.error_message for the failure reason. Common causes:\n- Missing required fields (phone, address, category)\n- Invalid data format (bad phone number, malformed URL)\n- Directory-specific restrictions (business type not allowed, location not supported)\n- Authentication issues (OAuth token expired, connection broken)\n - SYNC_STATUS_CLAIMED: SYNC_STATUS_CLAIMED means the listing exists but is claimed/owned by someone else.\nUser action: Business owner must claim/verify ownership on the directory before we can sync.\nThis is common for Google, Yelp, and other directories that require ownership verification.\n - SYNC_STATUS_UNAVAILABLE: SYNC_STATUS_UNAVAILABLE means we cannot sync to this directory due to eligibility constraints.\nUser action: Check hidden_reason for explanation (e.g., \"Not available in your country\", \"Requires LSP subscription\")\n - SYNC_STATUS_SUBMITTED: SYNC_STATUS_SUBMITTED means data was sent to the directory but we don't have confirmation of success.\nThis is used for directories (like Data Axle, Neustar) that don't provide real-time sync confirmation.\nUser action: Wait 24-48 hours for the directory to process the submission.\n - SYNC_STATUS_NOT_CONNECTED: SYNC_STATUS_NOT_CONNECTED means no OAuth account has been connected for this direct sync source.\nUser action: Connect an account via OAuth to enable syncing.\nThis applies to direct sync sources (Google, Facebook, X, Apple) that require OAuth.\n - SYNC_STATUS_RECONNECT_REQUIRED: SYNC_STATUS_RECONNECT_REQUIRED means an OAuth account was previously connected but the token is broken,\nexpired, or the account is no longer authenticated. Data may be stale.\nUser action: Reconnect the account via OAuth to resume syncing.\nThis is more urgent than NOT_CONNECTED as there may be stale data from the previous connection."
      enum:
      - SYNC_STATUS_UNSET
      - SYNC_STATUS_SYNCING
      - SYNC_STATUS_PARTIALLY_SYNCED
      - SYNC_STATUS_SUCCESS
      - SYNC_STATUS_FAILED
      - SYNC_STATUS_CLAIMED
      - SYNC_STATUS_UNAVAILABLE
      - SYNC_STATUS_SUBMITTED
      - SYNC_STATUS_NOT_CONNECTED
      - SYNC_STATUS_RECONNECT_REQUIRED
      type: string
    v1Provider:
      default: PROVIDER_UNSPECIFIED
      description: "Provider indicates how listing data is synced to a directory.\nThis is critical for understanding the difference between managed (LSP) and manual (RM) listings.\n\n - PROVIDER_UNSPECIFIED: PROVIDER_UNSPECIFIED means manual submission via Reputation Management (RM).\nThese listings must be manually created and updated by the user.\nThey do NOT automatically sync when the business profile changes.\n - PROVIDER_UBERALL: PROVIDER_UBERALL means synced automatically via Uberall (LSP provider for European/international directories).\nRequires active Listing Sync Pro subscription with Uberall.\n - PROVIDER_YEXT: PROVIDER_YEXT means synced automatically via Yext (LSP provider for North American directories).\nRequires active Listing Sync Pro subscription with Yext.\n - PROVIDER_DIRECT: PROVIDER_DIRECT means synced directly via OAuth (Google, Facebook, Apple, Bing).\nNo LSP subscription required - user just needs to connect their account."
      enum:
      - PROVIDER_UNSPECIFIED
      - PROVIDER_UBERALL
      - PROVIDER_YEXT
      - PROVIDER_DIRECT
      type: string
    v1AccuracyStatus:
      default: ACCURACY_STATUS_INVALID
      description: "AccuracyStatus represents the overall accuracy state of a listing on a directory.\nThis is determined by comparing the business profile data against what's actually live on the directory (scraped data).\n\n - ACCURACY_STATUS_INVALID: ACCURACY_STATUS_INVALID means the accuracy data could not be interpreted or there was an error during scraping.\nThis is a technical error, not a listing problem.\n - ACCURACY_STATUS_UNKNOWN: ACCURACY_STATUS_UNKNOWN means either no scraped data was found (listing might not exist yet), or we haven't scraped this source yet.\nCommon for new listings that haven't been indexed by the directory, or directories we don't actively scrape.\n - ACCURACY_STATUS_ACCURATE: ACCURACY_STATUS_ACCURATE means the scraped listing data matches the business profile perfectly.\nAll NAP fields match - the listing is correct and healthy.\n - ACCURACY_STATUS_INACCURATE: ACCURACY_STATUS_INACCURATE means the scraped listing has one or more discrepancies compared to the business profile.\nCheck anchor_data_matches to see exactly which fields don't match.\nUser action: Review and correct the inaccurate fields, then wait for next sync.\n - ACCURACY_STATUS_UNAVAILABLE: ACCURACY_STATUS_UNAVAILABLE means this directory doesn't support accuracy reporting (we don't scrape it).\nCommon for data aggregators (Neustar, Data Axle) that don't have public listing pages to scrape."
      enum:
      - ACCURACY_STATUS_INVALID
      - ACCURACY_STATUS_UNKNOWN
      - ACCURACY_STATUS_ACCURATE
      - ACCURACY_STATUS_INACCURATE
      - ACCURACY_STATUS_UNAVAILABLE
      type: string
    v1AnchorDataMatches:
      properties:
        address:
          title: 'address is true if the directory''s street address matches the expected address

            Address mismatches prevent customers from finding the business'
          type: boolean
        city:
          title: city is true if the directory's city matches the expected city
          type: boolean
        companyName:
          title: 'company_name is true if the directory''s business name matches the expected name

            Name mismatches are common causes of listing inaccuracy'
          type: boolean
        country:
          title: country is true if the directory's country matches the expected country
          type: boolean
        phone:
          title: 'phone is true if the directory''s phone number matches the expected phone

            Phone mismatches are critical - often the most important field for users'
          type: boolean
        state:
          title: state is true if the directory's state/province matches the expected state
          type: boolean
        website:
          title: website is true if the directory's website matches the expected website
          type: boolean
        zip:
          title: zip is true if the directory's zip code matches the expected zip code
          type: boolean
      title: 'AnchorDataMatches contains field-by-field accuracy comparison results.

        Each boolean indicates if the expected value (from AnchorData) matches what''s currently live on the directory.

        True = field is accurate, False = field is inaccurate or missing on the directory.

        This is critical for answering "which specific fields are wrong on this listing?"'
      type: object
    v1GetSyncDataResponse:
      description: Contains sync status and accuracy information for all relevant listing directories for a business.
      properties:
        sources:
          description: 'Output only. An array of directory-specific sync and accuracy data.

            Each entry represents one directory where the business has or could have a listing.'
          items:
            $ref: '#/components/schemas/v1SyncData'
          readOnly: true
          type: array
      title: GetSyncDataResponse
      type: object
  securitySchemes:
    OAuth2:
      flows:
        authorizationCode:
          authorizationUrl: https://sso-api-prod.apigateway.co/oauth2/auth
          scopes:
            admin: Allows the application to perform administrative tasks that you have access to across the platform
            business-app: Allows the application to manage all features of Business App
          tokenUrl: https://sso-api-prod.apigateway.co/oauth2/token
      type: oauth2