API Call Structure

Page Summary

• Google Ads API calls can be made using either gRPC (preferred) or REST.

• Resource names identify most objects in the API and also serve as URLs for the REST interface.

• Composite IDs are used for objects whose IDs are not globally unique, constructed by prepending the parent ID and a tilde.

• Required request headers include Authorization (OAuth2 access token) and developer-token.

• The login-customer-id header specifies the customer ID for the authorized customer, particularly required when accessing accounts through a manager account.

This guide describes the common structure of all API calls.

If you're using a client library to interact with the API, you won't need to know the underlying request details. However, some knowledge about the API call structure can come in handy when testing and debugging.

Google Ads API is a gRPC API, with REST bindings. This means that there are two ways of making calls to the API.

Preferred:

1. Create the body of the request as a protocol buffer.

2. Send it to the server using HTTP/2.

3. Deserialize the response to a protocol buffer.

4. Interpret the results.

Most of our documentation describes using gRPC.

Optional:

1. Create the body of request as a JSON object.

2. Send it to the server using HTTP 1.1.

3. Deserialize the response as a JSON object.

4. Interpret the results.

Refer to the REST interface guide for more information on using REST.

Note: This guide describes the structure and transport headers common to both gRPC and REST protocols.

Resource names

Most objects in the API are identified by their resource name strings. These strings also serve as URLs when using the REST interface. See the REST interface's Resource Names for their structure.

Key Point: Check out the resources documentation, for all supported resources and their path representation (resource_name). The same format is used for other services.

Composite IDs

If the ID of an object is not globally unique, a composite ID for that object is constructed by prepending its parent ID and a tilde (~).

For example, since an ad group ad ID is not globally unique, we prepend its parent object (ad group) ID to it to make a unique composite ID:

• AdGroupId of 123 + ~ + AdGroupAdId of 45678 = composite ad group ad ID of 123~45678.

Request headers

These are the HTTP headers (or grpc metadata) that accompany the body in the request:

Authorization

You must include an OAuth2 access token in the form of Authorization: Bearer YOUR_ACCESS_TOKEN that identifies either a manager account acting on behalf of a client, or an advertiser directly managing their own account. Directions for retrieving an access token can be found in the OAuth2 guide. An access token is valid for an hour after you acquire it; when it expires, refresh the access token to retrieve a new one. Note that our client libraries automatically refresh expired tokens.

If you encounter authorization errors, ensure you are using the correct credentials and have sufficient permissions. A USER_PERMISSION_DENIED error indicates that the authenticated user may not have access to the customer account specified in the request. Refer to Google Ads Access Levels for details on managing permissions.

developer-token

A developer token is a 22-character string that uniquely identifies a Google Ads API developer. An example developer token string is ABcdeFGH93KL-NOPQ_STUv. The developer token should be included in the form of developer-token : ABcdeFGH93KL-NOPQ_STUv.

login-customer-id

This is the customer ID of the authorized customer to use in the request, without hyphens (-). If your access to the customer account is through a manager account, this header is required and must be set to the customer ID of the manager account. If you fail to include login-customer-id when you authenticate through a manager account, this results in an AuthorizationError.USER_PERMISSION_DENIED error. Review Common Errors for more information on this error type.

Key Term: The operating customer is the customer ID in the request payload. For example, the operating customer in the following CampaignBudgetService request is 1234567890:

https://googleads.googleapis.com/v24/customers/1234567890/campaignBudgets:mutate

Setting the login-customer-id is equivalent to choosing an account in the Google Ads UI after signing in or clicking on your profile image at the top right. If you don't include this header, it defaults to the operating customer.

Note: You can retrieve the list of accounts that are directly accessible with your OAuth credentials by issuing a CustomerService.ListAccessibleCustomers request. The login-customer-id is not required for this request type, and has no effect on the list of customers returned.

linked-customer-id

This header is required and used by partners (such as third-party app analytics providers or data partners) when acting on a linked Google Ads account. This header must specify the Customer ID of the Google Ads account that has the product link.

Consider the scenario where a partner needs to make API calls to a Google Ads account based on a product link.

• Advertiser: The Google Ads account being managed or updated by the API call. The ID of the Advertiser account is specified in the request. In REST, this is the customerId path parameter (for example, customers/1111111111/...), and in gRPC, this is the customer_id field in the request.
• Partner: The partner account (for example, a third-party app analytics provider or data partner).
• Linked account: The Google Ads account that has an established product link with Partner, granting Partner access to Advertiser.

A user who has access to Partner makes API calls to act on entities in Advertiser (for example, to upload conversions or manage user lists). Linked account can be Advertiser itself, or a manager account of Advertiser.

The request headers must be set as follows:

• Authorization: An OAuth2 token for a user who has access to Partner.
• developer-token: The developer token for the API application, typically associated with Partner.
• login-customer-id: The Customer ID of Partner. The authenticated user must have access to this account.
• linked-customer-id: The Customer ID of Linked account. This header signals that the authorization for this request relies on Linked account's product link with Partner.

There are two linking scenarios:

• If Advertiser has a direct product link with Partner, then Linked account is Advertiser, and linked-customer-id must be set to Advertiser's customer ID.
• If Advertiser is managed by a manager account that has a product link with Partner, then Linked account is the manager account, and linked-customer-id must be set to the manager's customer ID.

Example 1: Direct link

If Advertiser 1111111111 has a direct link with Partner 2222222222, and the API call is targeting customers/1111111111/...:

Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_TOKEN
login-customer-id: 2222222222
linked-customer-id: 1111111111

Example 2: Manager link

If Advertiser 1111111111 is managed by Manager 3333333333, Manager 3333333333 has a link with Partner 2222222222, and the API call is targeting customers/1111111111/...:

Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_TOKEN
login-customer-id: 2222222222
linked-customer-id: 3333333333

Response headers

The following headers (or grpc trailing-metadata) are returned with the response body. We recommend that you log these values for debugging purposes.

request-id

The request-id is a string that uniquely identifies this request.