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 worry about the underlying request details. However, knowing a bit about them 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] Create the body of the request as a protocol buffer, send it to the server using HTTP/2, deserialize the response to a protocol buffer, and interpret the results. Most of our documentation describes using gRPC.
[Optional] Create the body of request as a JSON object, send it to the server using HTTP 1.1, deserialize the response as a JSON object, and interpret the results. Refer to the REST interface guide for more information on using REST.
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.
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:
AdGroupIdof123+~+AdGroupAdIdof45678= composite ad group ad ID of123~45678.
Request headers
These are the HTTP headers (or grpc metadata) that accompany the body in the request:
Authorization
You need to 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.
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.
https://googleads.googleapis.com/v8/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 do not include this header, it defaults to the operating
customer.
linked-customer-id
This header is only used by third-party app analytics providers when uploading conversions to a linked Google Ads account.
Consider the scenario where users on account A provide read and edit access
to its entities to account B through a
ThirdPartyAppAnalyticsLink.
Once linked, a user on account B can make API calls against account A,
subject to the permissions provided by the link. In this case, the API-calling
permissions to account A are determined by the third-party link to account B,
rather than the manager-account relationship that is used in other API calls.
The third-party app analytics provider makes an API call as follows:
linked-customer-id: The third-party app analytics account that uploads the data (accountB).customer-id: The Google Ads account to which data is uploaded (accountA).login-customer-idandAuthorizationheader: A combination of values to identify a user who has access to accountB.
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.