> For the complete documentation index, see [llms.txt](https://docs.sprinthub.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sprinthub.com/en/topics/integrations/integration-google-ads-and-gmail/google-conversions-api-parameters-google-ads-conversion-api.md).

# Google Conversions 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:

* 🔗 Google Ads API – Conversion action categories\
  <https://developers.google.com/google-ads/api/docs/conversions/categories?hl=pt-br>
* 🔗 Google Ads API - Custom conversion variables\
  <https://developers.google.com/google-ads/api/docs/conversions/conversion-custom-variables?hl=pt-br>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.sprinthub.com/en/topics/integrations/integration-google-ads-and-gmail/google-conversions-api-parameters-google-ads-conversion-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.