Ctrlk
Site SprintHub
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Google Conversion API Parameters (Google Ads Conversion API)

Introduction

The Google Conversion API, also known as Google Ads Conversion API, is a safer and more reliable way to send conversion events directly from the server to Google Ads. Unlike traditional pixel (tag) tracking, this integration reduces data loss caused by ad blockers, cookie restrictions, and browser privacy policies.

With the API, conversions are sent in a server-side, ensuring greater measurement accuracy and better campaign optimization.

What is the Google Conversion API for?

The Conversion API allows:

  • 📊 Measure conversions more accurately

  • 🔒 Reduce the impact of ad blockers and cookies

  • 🚀 Improve campaign optimization and learning

  • 🔁 Send online and offline events (e.g., sales, leads, payments)

  • 📈 Increase the reliability of attribution data

Difference between Google Tag and Conversion API

Google Tag (Client-side)
Conversion API (Server-side)

Runs in the browser

Runs on the server

Can be blocked

Does not suffer browser blocking

Depends on cookies

Less dependence on cookies

May lose events

Higher delivery rate

💡 The combined use of the Tag + Conversion API is the best practice recommended by Google.

Main events sent

The most common events sent via the API include:

  • Lead (sign-up / form submitted)

  • Purchase (purchase completed)

  • AddToCart (add to cart)

  • BeginCheckout (checkout started)

  • Offline conversions

Each event can contain parameters such as:

  • Conversion value

  • Currency

  • Event ID

  • Attribution data

How the integration works (overview)

  1. The user performs an action (e.g., form submission)

  2. The system records the event

  3. The event is sent from the server to the Google Ads API

  4. Google processes and attributes the conversion to the campaign

Requirements to use the Google Conversion API

To use the API, you need:

  • Active account in the Google Ads

  • Conversions configured in Google Ads

  • Administrative access to the account

  • Credential generation (token/API key)

  • Proper user consent, in accordance with the LGPD

Recommended best practices

  • ✅ Use event deduplication (Event ID)

  • ✅ Send as many parameters as possible

  • ✅ Combine Google Tag + API

  • ✅ Ensure compliance with LGPD and Google's policies

  • ✅ Monitor conversion status in Google Ads

Common errors and precautions

  • ❌ Duplicate conversions due to lack of deduplication

  • ❌ Invalid token or no permission

  • ❌ Event not configured in Google Ads

  • ❌ Sending data outside the required standard

Benefits for your operation

By using the Google Conversion API, your company gains:

  • More reliable data

  • Better campaign performance

  • Less dependence on cookies

  • Greater control over events and attribution

Categories of conversion actions in the Google Ads API

When configuring the Google Conversion API, it is essential to correctly choose the conversion action category (ConversionActionType). These categories determine how Google Ads interprets, attributes, and optimizes each event.

Below are the main categories supported by the API, according to Google’s official documentation.

Offline conversions

Used to track conversions that happen outside the digital environment, such as in-person sales or phone contacts.

Type (API)
Origin in Google Ads
Description

UPLOAD_CLICKS

Click conversions / Leads

Import of offline click-based conversions

UPLOAD_CALLS

Call conversions

Import of phone call conversions

STORE_SALES

In-store sales

Import of physical sales

Online conversions (Website)

Allow you to track actions performed directly on the site, such as purchases, forms, and clicks.

Type (API)
Origin in Google Ads
Description

WEBPAGE

Website / GA4

Page load conversions

WEBPAGE_ONCLICK

Website / GA4

Conversions from element clicks

CLICK_TO_CALL

Phone clicks

Clicks on phone numbers on mobile devices

⚠️ Website conversions require the global_site_tag and the event_snippet, in addition to correct event mapping.

App conversions

Used to measure installations and actions within mobile apps.

Type (API)
Origin in Google Ads

GOOGLE_PLAY_DOWNLOAD

Google Play installs

GOOGLE_PLAY_IN_APP_PURCHASE

In-app purchases

💡 For installation conversions, the category must be set to DOWNLOAD.

Phone call conversions

Indicated for businesses that receive leads or sales by phone.

Type (API)
Origin in Google Ads
Description

AD_CALL

Ad calls

Calls generated directly from ads

WEBSITE_CALL

Website calls

Calls originating from numbers displayed on the site

CLICK_TO_CALL

Click to call

Only the click on the number (without tracking the call)

Optimized conversions

The optimized conversions complement the data sent, using the business's own information (such as email or phone) in a secure and encrypted way.

Type (API)
Use

UPLOAD_CLICKS

Optimized conversions for leads

WEBPAGE

Optimized conversions for web

These conversions help Google improve campaign attribution and performance.

Integrations with Google Analytics (GA4)

Conversions imported from GA4 use specific types:

  • GOOGLE_ANALYTICS_4_CUSTOM

  • GOOGLE_ANALYTICS_4_PURCHASE

These conversions can be enabled, categorized, and used for bidding directly in Google Ads, respecting API limitations.

Best practices when choosing the category

  • ✅ Choose the correct category according to the conversion source

  • ✅ Avoid mixing online and offline conversions

  • ✅ Use optimized conversions whenever possible

  • ✅ Ensure deduplication between Tag and API

  • ✅ Respect privacy guidelines (LGPD)

Custom conversion variables

The custom conversion variables allow associating additional information with conversions imported via Google Ads API, functioning as tags that enrich the sent data. With them, it is possible to create more detailed and segmented reports in Google Ads.

What are they for?

They are used to add extra attributes to a conversion, such as status, category, origin, or any relevant business information.

Practical example: When importing a product purchase conversion, such as a new blue hat, it is possible to associate tags such as:

  • color: blue

  • status: new

How custom variables work

  1. Each custom variable corresponds to a tag

  2. You can create as many variables as needed

  3. These variables are linked to conversions at the time of import

The required fields of a custom variable (ConversionCustomVariable) are:

  • name: identifies the variable (must be unique)

  • tag: tag name that will be used in the conversion (e.g., color, status)

⚠️ Check the field limitations directly in the official Google Ads documentation.

Creation and management

Management of custom conversion variables is done through the ConversionCustomVariableService.

To create new variables:

  • Use the method MutateConversionCustomVariables

  • Send one or more ConversionCustomVariableOperation

  • In each operation, set the field create with the variable data

After creation, the variable may have the statuses:

  • ENABLED (active)

  • ACTIVATION_NEEDED (needs activation)

The status can be checked in the API response.

Use of variables in conversion import

When importing a conversion (such as ClickConversion), use the field custom_variables to provide all created variables.

Each variable must contain:

  • conversion_custom_variable: resource name of the created variable

  • value: value that will be associated with the conversion (e.g., blue, new)

This data then becomes available for segmentation and advanced reporting in Google Ads.

Conclusion

The correct definition of the conversion action categories is essential for the Google Conversion API works efficiently. When well configured, they guarantee more reliable data, better attribution, and more performant campaigns within Google Ads.

Whenever possible, use the API together with Google Tag and keep your conversion actions aligned with your business strategy.

Official reference

This article was prepared based on the official Google Ads documentation:

PreviousCreating Conversions in Google Ads to send via SprintHub
NextConnect Gmail in real time (Pub/Sub)

Last updated

Was this helpful?