Calling the Apple Ads Platform API

Overview

Before you can call the API, you need to perform the implementation steps in Implementing OAuth for the Apple Ads Platform API.

To call the Apple Ads Platform API, pass your access token as Bearer in the authorization header of HTTP requests. The value tells the API that the caller holds a valid token authorized to access the API and perform the specified actions.

The following is an example call to the API:

curl "https://api.ads.apple.com/v1/" \
-H "Authorization: Bearer {access_token}" \
-H "X-AP-Context: adAccountId={adAccountId}"

New to the API? See Managing Ad Accounts and API Access for a complete walkthrough that shows where {access_token} and {adAccountId} come from, ending in a real request like the one above.

Include Required Headers

Include the following headers with every request:

To return the userId and orgId of an API caller, use Get Me Details.

Confirm Product Feature and Delegation Requirements

The productFeatures array on an ad account determines whether it can run App Store or Apple Maps campaigns. App Store ad accounts carry APPSTORE_APP_MANUAL, and Apple Maps ad accounts carry BUSINESS_BRAND_MANUAL. An account authorized for App Store can’t run campaigns on Apple Maps, and vice versa.

In addition to productFeatures, the ad account must also have a delegations entry linking it to the appropriate advertiser resource. App Store accounts need a CONTENT_PROVIDER delegation with the CPID as resourceId, and Apple Maps accounts need a BUSINESS_BRAND delegation with the Brand ID as resourceId.

Both must be in place before campaigns can go live. See ProductFeatures for details.

Structure Endpoint Calls

The Apple Ads API uses a REST data model. To call endpoint resources, use CRUD (create, read, update, delete) and query functions. In some cases, the call may also include a query parameter. The Apple Ads Platform API has a hierarchy with most entities as top-level resources. For example, to get all keywords in an ad group, send the adGroupId as a filter to the keywords query endpoint, like this:

POST /v1/keywords/query

{
  "filters": [
    {
      "field": "adGroupId",
      "operator": "EQUALS",
      "value": 542317095
    }
  ]
}

Perform Partial Updates

A partial update changes a subset of object properties instead of the entire set of object properties. The API supports partial updates for most PUT calls. Only include the fields you want to change. The API leaves unset fields unchanged. Array fields are an exception. When you include an array in a PUT request, it replaces the existing values entirely. To add a single item to an array field, retrieve the current array first and send the complete desired state.

For example, the following payload updates the name and status of a campaign:

PUT /v1/campaigns/{id}

{
  "name": "Updated Campaign Name",
  "status": "PAUSED"
}

Perform Bulk Operations

Bulk endpoints accept multiple items in a single request. All bulk endpoints share the same request structure, with an items array where each element carries a correlationId and a data object containing the operation payload. The correlationId is a client-supplied integer that matches each result in the response back to its input item.

Set allowPartialSuccess: true in the request body to enable partial success semantics, as shown below. The API processes items that pass validation even if other items fail. When you omit allowPartialSuccess or set it to false, any single item failure rejects the entire batch.

POST /v1/keywords/bulk-create

{
  "allowPartialSuccess": true,
  "items": [
    {
      "correlationId": 0,
      "data": {
        "adGroupId": 555666777,
        "text": "photo editor",
        "matchType": "EXACT"
      }
    }
  ]
}

The response returns a result array with one entry per input item. Each entry includes correlationId, operation, success, and either the entity you created or updated or per-item error details.

For supported entities and endpoint paths, see Bulk Operations Endpoints.

Query the API

The Apple Ads Platform API uses a common query parameter structure in all /query endpoints. Define filtering, sort order, and pagination for a query. The API doesn’t return deleted entities unless the user specifically filters to include them.

To return all records and values for supported endpoints, use the /query endpoint with an empty payload.

The /query request structure resembles the following:

POST /v1/campaigns/query

{
  "filters": [
    {
      "field": "status",
      "operator": "EQUALS",
      "value": "ENABLED"
    }
  ],
  "sorting": [
    {
      "field": "name",
      "order": "ASC"
    }
  ],
  "pagination": {
    "offset": 0,
    "pageSize": 10,
    "fetchTotalCount": true
  }
}

For more illustrative examples, see Managing Reports.

Structure the Query Request

The API performs all querying via POST requests to /query endpoints, not GET with query parameters. The pattern is consistent across every entity type.

The table below details the query request fields:

The table below details the filters objects:

The table below details the sorting objects:

The table below details the request pagination objects:

Explore the Query Objects

The following objects support querying:

• QueryRequest: Drives the query. Contains optional filters, sorting, and pagination.

• QueryFilter: A single filter condition. Contains field, operator (see QueryFilterOperator), value, and optional ignoreCase flag.

• QueryFilterOperator: The comparison operators supported in query filters.

• QuerySort: Defines the sort order for a single field. Contains the field and order (see QuerySortOrder).

• QuerySortOrder: The enumeration controlling the sort direction of ASC or DESC.

• QueryPagination: Controls the page size and offset for the result set. Contains pageSize, offset, and fetchTotalCount.

• QueryResponse: The paginated response wrapper that contains a paginated result array of entity objects and pagination metadata.

• QueryPaginationResult: Reflects the pagination state of the response. Contains pageSize, offset, and totalCount.

• Error: The top-level error returned when the query fails (for example, an invalid filter field).

• ErrorDetail: Granular error detail with code and message.

Interpret API Responses

In API responses, the result field is the main result object across all responses.

The response object fields are as follows:

Some endpoints instead return a dedicated ErrorResponse envelope on failure, which wraps a single error field containing the Error object (see Error) rather than embedding error alongside result and pagination. See ErrorResponse for details.

The response pagination object fields are as follows:

The error object fields are as follows:

The error detail object fields are as follows:

Successful Response

A successful response example:

{
  "result": [
    {
      "id": 542370549,
      "name": "AwayFinder_Brand"
    },
    {
      "id": 542370539,
      "name": "AwayFinder_Category"
    }
  ],
  "pagination": {
    "offset": 0,
    "pageSize": 10,
    "totalCount": 12
  }
}

The table below details the error responses:

A detailed error message example:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation errors found",
    "details": [
      {
        "code": "DUPLICATE_NAME",
        "message": "AdGroup name already exists under this Campaign."
      }
    ]
  }
}

Handle Rate Limits

Every response, successful or not, includes a set of RateLimit-* headers you can use to pace requests and avoid a 429. See Applying Rate Limits for the full header reference and a sample backoff implementation.

Topics

Query Objects

• QueryRequest
• QueryFilter
• QuerySort
• QueryPagination
• QueryResponse
• QueryPaginationResult

Type Aliases

• QueryFilterOperator
• QuerySortOrder

Response

• Response

Error Responses

• Error
• ErrorDetail
• ErrorResponse

See Also

Essentials

• Implementing OAuth for the Apple Ads Platform API
• Using Client Libraries
• Applying Rate Limits
• Advertising Your App on the App Store
• Advertising Your Business on Apple Maps