Automating Google LSA Lead Ratings Through the Google Ads API

2026-11-17来源 HackerNoonEnglish

Google Local Services Ads (LSA) lead feedback can be submitted programmatically through the Google Ads API using LocalServicesLeadService.ProvideLeadFeedback(). But building reliable automation around this method requires more than sending a rating request. Agencies must preserve lead identity, translate CRM outcomes into Google's supported survey enums, check whether feedback has already been submitted, and maintain an auditable record of every API operation.

This creates an interesting engineering problem: how do you turn subjective CRM lead-quality assessments into valid, traceable feedback without sending inaccurate or duplicate classifications to Google?

For agencies managing hundreds or thousands of leads across multiple client accounts, manual rating is difficult to scale. Automated submission can reduce operational work, but poorly designed automation can introduce a different problem: systematically sending incorrect feedback.

The right architecture needs a validation layer between the CRM and Google's API.

1. Understanding the ProvideLeadFeedback API

Google exposes lead feedback submission through the LocalServicesLeadService service.

The relevant method is:

LocalServicesLeadService.ProvideLeadFeedback() 

It accepts a ProvideLeadFeedbackRequest and returns a ProvideLeadFeedbackResponse.

The request contains three important components:

Parameter

Purpose

Requirement

resource_name

Identifies the Local Services lead

Required

survey_answer

Records the advertiser's satisfaction rating

Required

survey_details

Contains additional satisfaction or dissatisfaction information

Union field; provide the applicable details

The survey_details field supports either survey_dissatisfied or survey_satisfied. These are alternative branches of a union field, so an integration should not attempt to populate both in one request.

The API also requires the Google Ads OAuth scope:

https://www.googleapis.com/auth/adwords 

This is important for agencies building integrations because the authentication layer must have the appropriate authorization to operate on the Google Ads customer account.

Sources: ProvideLeadFeedback method, ProvideLeadFeedbackRequest.

2. Lead identity must be resolved before feedback submission

The first architectural requirement is reliable lead identification.

Google's LocalServicesLead resource exposes a resource_name in this format:

customers/{customer_id}/localServicesLeads/{lead_id} 

For example:

customers/1234567890/localServicesLeads/987654321 

This resource name should be the primary external identifier used by the feedback integration.

A CRM may identify the same record through an internal ID, telephone number, email address, or booking reference. None of those should replace Google's lead resource name when constructing the API request.

A useful internal data model would preserve both identifiers:

{ "crm_lead_id": "CRM-2026-00451", "google_ads_customer_id": "1234567890", "google_lead_resource_name": "customers/1234567890/localServicesLeads/987654321", "lead_created_at": "2026-11-10T09:35:00Z", "feedback_status": "PENDING" } 

This is an illustrative internal schema, not a Google-defined resource.

The distinction becomes important when a customer contacts the business multiple times. A CRM might merge several interactions into one customer record, while Google exposes individual lead resources.

If an agency submits feedback using the wrong lead resource name, it risks rating a different interaction from the one assessed by the CRM.

Google's documentation also exposes the lead's campaign, category, service, status, and creation timestamp. These fields can help the integration reconcile the correct record before submission.

3. Why CRM classifications cannot be copied directly into Google's survey enums

This is where most of the automation logic belongs.

A typical home-services CRM might classify leads using statuses such as:

  • Qualified
  • Unqualified
  • Spam
  • Duplicate
  • Booked
  • Completed
  • No response
  • Outside service area
  • Wrong service requested

Google's API does not accept arbitrary CRM labels as survey answers. It expects supported enum values.

In API v26, the SurveyAnswer enum includes:

Enum

Meaning

VERY_DISSATISFIED

Very dissatisfied with the lead

DISSATISFIED

Dissatisfied with the lead

NEUTRAL

Neutral about the lead

SATISFIED

Satisfied with the lead

UNSPECIFIED

Not specified

UNKNOWN

Return-value placeholder

Do not confuse a CRM's operational status with the advertiser's satisfaction rating.

For example, a lead marked BOOKED may be a satisfactory lead, but a booking is not automatically proof that the advertiser wants to submit a particular satisfaction rating. The business's actual assessment should drive the feedback.

Similarly, a lead marked UNQUALIFIED does not automatically mean VERY_DISSATISFIED. The reason for that classification matters.

Source: Google Ads API v26 SurveyAnswer.

4. Building a CRM-to-Google enum mapping layer

Instead of translating CRM labels directly into API values, create an explicit mapping table.

For example:

CRM classification

Possible Google feedback classification

Validation requirement

Spam

DISSATISFIED

Confirm the interaction is genuinely spam

Duplicate

DISSATISFIED

Verify that the Google lead is actually a duplicate

Outside service area

DISSATISFIED

Confirm geographical mismatch

Wrong job type

DISSATISFIED

Confirm the requested service is not offered

Customer not ready to book

DISSATISFIED

Confirm the customer interaction supports this reason

Booked

SATISFIED

Require an actual satisfaction assessment

Completed

SATISFIED

Require an actual satisfaction assessment

No response

No automatic rating

Insufficient evidence to determine satisfaction

The table illustrates a possible agency mapping policy. It is not a Google-prescribed mapping.

This distinction also matters when an agency receives a charged lead that it considers unsatisfactory. A dissatisfaction rating and a billing status represent different records and should be reconciled separately. See this discussion on reconciling dissatisfied lead ratings with charged GLSA leads.

For dissatisfied leads, Google provides a separate SurveyDissatisfiedReason enum:

  • DUPLICATE
  • GEO_MISMATCH
  • JOB_TYPE_MISMATCH
  • NOT_READY_TO_BOOK
  • OTHER_DISSATISFIED_REASON
  • SOLICITATION
  • SPAM
  • UNSPECIFIED
  • UNKNOWN

The API also supports an other_reason_comment field. When OTHER_DISSATISFIED_REASON is selected, this comment is required.

This creates an important validation rule: an integration must not submit a generic dissatisfaction reason without supplying the required comment when that specific enum is used.

Sources: SurveyDissatisfiedReason, SurveyDissatisfied.

5. The request payload should be generated only after validation

Once the integration has resolved the lead identity and validated the feedback classification, it can construct the API request.

For example, a dissatisfied lead caused by a geographical mismatch could be represented conceptually as:

{ "resourceName": "customers/1234567890/localServicesLeads/987654321", "surveyAnswer": "DISSATISFIED", "surveyDissatisfied": { "surveyDissatisfiedReason": "GEO_MISMATCH" } } 

This illustrates the request fields in REST-style JSON. The exact wire representation depends on the API endpoint and client library.

For a different reason, such as spam, the enum value would change:

{ "resourceName": "customers/1234567890/localServicesLeads/987654321", "surveyAnswer": "DISSATISFIED", "surveyDissatisfied": { "surveyDissatisfiedReason": "SPAM" } } 

A satisfied lead follows the alternative survey_satisfied branch and requires a supported SurveySatisfiedReason.

The important engineering rule is to generate the request from a validated classification object rather than allowing CRM fields to flow directly into the API payload.

This separates business logic from API serialization and makes the integration easier to test when Google's enum definitions change.

6. lead_feedback_submitted should act as a pre-submission control

Google exposes the lead_feedback_submitted field on the LocalServicesLead resource.

It is an output-only Boolean field:

  • true: The advertiser has submitted feedback for the lead.
  • false: Feedback has not been submitted.

An integration can retrieve this field through a Google Ads API query before attempting submission.

For example:

SELECT local_services_lead.resource_name, local_services_lead.id, local_services_lead.lead_feedback_submitted, local_services_lead.lead_status, local_services_lead.creation_date_time FROM local_services_lead 

The returned resource name can be matched against the CRM's stored Google lead identifier.

A simplified decision process would be:

Retrieve Google lead | v Read lead_feedback_submitted | v Is feedback already submitted? / \ Yes No | | v v Skip Validate CRM classification | v Build feedback request | v Call ProvideLeadFeedback 

This is a useful control, but it should not be treated as a complete duplicate-prevention mechanism.

It is equally important to distinguish feedback submission from billing changes. The fact that an advertiser has submitted a lead rating does not, by itself, establish that the lead's billing status has changed. This distinction is discussed in whether GLSA billing status changes after Lead Rating feedback submission.

There is a possible race condition: two workers can retrieve the same lead, both observe false, and both attempt submission.

That is why the agency should maintain its own submission state in addition to Google's Boolean field.

7. Preventing duplicate submissions requires application-level state management

Consider an agency processing 5,000 leads across several client accounts.

A scheduled worker retrieves leads that have not been rated and places them into a processing queue. If two workers pick up the same lead simultaneously, both may attempt to submit feedback.

A basic database check is not enough unless the operation is atomic.

An internal state machine could look like this:

State

Meaning

PENDING

Lead is eligible for evaluation

VALIDATING

CRM data and Google lead identity are being checked

READY_TO_SUBMIT

Feedback payload has passed validation

SUBMITTING

API request is in progress

SUBMITTED

API confirmed successful submission

FAILED_RETRYABLE

Temporary failure; retry may be appropriate

FAILED_FINAL

Request requires correction or manual review

ALREADY_SUBMITTED

Google reports feedback has already been submitted

The application should enforce a unique processing key based on the Google customer ID and lead resource name.

For example:

1234567890: customers/1234567890/localServicesLeads/987654321 

A database transaction or atomic conditional update can reserve that record for one worker.

However, there is an important distributed-systems issue.

Suppose the API accepts the request, but the network connection drops before the application receives the response. The worker cannot immediately know whether Google processed the submission.

Blindly retrying the request could create a duplicate attempt.

The correct response is to mark the operation as having an unknown outcome, retrieve the lead again, and inspect lead_feedback_submitted before deciding what to do next.

Do not assume that ProvideLeadFeedback offers an application-controlled idempotency key unless Google explicitly documents one.

8. API errors need classification before retry

A production integration should not treat every API failure as a temporary network issue.

There are several broad failure categories:

Failure category

Example

Recommended handling

Authentication

Expired or invalid credentials

Refresh or reauthorize

Authorization

Account access is insufficient

Check customer access and permissions

Invalid request

Missing resource name or invalid enum

Correct the payload

Data mismatch

CRM record points to the wrong Google lead

Reconcile the identifiers

Already submitted

Feedback state has changed

Retrieve the lead and reconcile

Rate limiting

Request quota exceeded

Apply controlled backoff

Transient service failure

Temporary service or network issue

Retry after checking submission state

The precise error code and response should determine the action. The categories above are an application-level handling strategy, not a list of guaranteed ProvideLeadFeedback error codes.

A useful retry policy distinguishes between retryable and non-retryable errors.

For temporary failures, exponential backoff with jitter can prevent multiple workers from overwhelming the API:

import randomimport timedef retry_delay(attempt): base_delay = 2 ** attempt jitter = random.uniform(0, 1) return min(base_delay + jitter, 60) 

This is illustrative retry logic, not Google's official retry implementation.

Invalid enums, missing required fields, and incorrect resource names should not be retried unchanged. They require data correction.

For ambiguous outcomes, check the lead's feedback status before another submission attempt.

Google's API error-handling guidance and the method's reference should be used to validate the exact error codes encountered in production.

9. The audit ledger should preserve the complete feedback lifecycle

A successful API response is not a complete audit trail.

Agencies need to know:

  • Which Google lead was rated?
  • Which CRM record supplied the classification?
  • Who or what approved the rating?
  • Which enum values were submitted?
  • Which API version processed the request?
  • When was the request sent?
  • What response did Google return?
  • Was the submission later verified?

A separate feedback ledger can preserve this information.

For example:

{ "feedback_event_id": "FB-2026-00091", "customer_id": "1234567890", "lead_resource_name": "customers/1234567890/localServicesLeads/987654321", "crm_lead_id": "CRM-2026-00451", "survey_answer": "DISSATISFIED", "survey_dissatisfied_reason": "GEO_MISMATCH", "api_version": "v26", "submission_status": "SUBMITTED", "submitted_at": "2026-11-15T10:30:00Z", "verified_feedback_submitted": true } 

This is a proposed internal schema, not a Google API response.

The ledger should be append-oriented. If a classification changes before submission, record the correction. If an API request fails, preserve the failed attempt and its error details rather than overwriting the original event.

That makes it possible to reconstruct the complete lifecycle of a lead-rating operation.

It also helps agencies investigate differences between CRM reporting and Google's lead feedback records.

10. Multi-account automation needs customer-level authorization boundaries

Agencies frequently manage multiple Google Ads customer accounts under a manager account.

A feedback automation system should therefore separate the agency's internal client identity from Google's customer ID.

A typical processing record should include:

agency_client_id manager_customer_id client_customer_id google_lead_resource_name crm_lead_id oauth_authorization_reference 

The API request must be executed with valid authorization and access to the customer account that owns the lead.

The method requires the adwords OAuth scope, but having that scope alone does not grant access to every client account. The authenticated user or application must also have the necessary Google Ads account permissions.

For security and operational control, each client's feedback queue should be processed within its own authorization context. A failure in one account should not block feedback processing for unrelated clients.

This also makes it easier to isolate permission errors, audit individual client activity, and prevent cross-account lead attribution mistakes.

11. API version changes can affect the feedback pipeline

Google Ads API integrations need a version-management strategy.

The current documentation provides the v26 method reference, while earlier versions have their own resource and enum definitions.

An agency should not assume that a successful implementation against one version will remain valid indefinitely.

A version-aware integration should:

  1. Keep API request construction separate from CRM classification logic.
  2. Maintain an explicit mapping between internal classifications and Google enums.
  3. Run schema and serialization tests against the target API version.
  4. Test required fields and union-field behaviour before deployment.
  5. Monitor API deprecation announcements.
  6. Preserve the API version used for each submission in the audit ledger.

The value of this separation becomes clear when Google adds or changes an enum. The agency should be able to update its mapping and validation layer without redesigning its CRM integration.

Google's current Local Services API documentation also explains how lead resources are retrieved and how feedback status is exposed.

12. A reference architecture for automated LSA lead feedback

The complete system can be organised into six layers.

  • CRM and lead management: Lead outcomes, customer interactions, booking and job records
  • Identity resolution: Match CRM records to Google lead resource names
  • Classification and validation: Map CRM outcomes to supported survey enums
  • Submission-state controller: Check lead_feedback_submitted and reserve processing state
  • Google Ads API adapter: Submit ProvideLeadFeedback requests
  • Audit and reconciliation ledger: Store responses, failures, timestamps and verified status

This architecture separates the business decision from the API operation.

That distinction is essential. The CRM determines what happened to the lead. The classification layer determines whether that outcome can be represented accurately using Google's survey model. The API adapter handles submission. The audit ledger preserves the evidence.

The architecture described here is a recommended implementation pattern, not Google's internal system design.

Conclusion: Lead feedback automation needs data governance

Google's ProvideLeadFeedback method gives agencies a way to submit LSA lead ratings programmatically. But the difficult part is not making the API request. It is ensuring that the request represents the correct lead, reflects a defensible business assessment, uses supported enum values, and is not submitted repeatedly.

Agencies should treat lead feedback as a controlled data pipeline rather than a background task that copies CRM statuses into Google Ads.

A reliable implementation needs identity resolution, explicit enum mapping, pre-submission validation, concurrency control, error classification, and an auditable submission history.

As LSA management becomes increasingly integrated with the Google Ads API, these controls will matter more to agencies managing multiple accounts and large lead volumes.

The objective should not be to submit more lead ratings automatically. It should be to submit accurate, traceable feedback that the agency can explain and audit later.

原文:https://www.a8q9.cn/en/article/automating-google-lsa-lead-ratings-through-the-google-ads-api-8aaec8.html

相关文章