<!--
{
  "availability" : [
    "Apple Ads Platform API: 1.0.0 -"
  ],
  "documentType" : "article",
  "framework" : "Apple-Ads-Platform-API",
  "identifier" : "/documentation/Apple-Ads-Platform-API/calling-apple-ads-platform-api",
  "metadataVersion" : "0.1.0",
  "role" : "collectionGroup",
  "title" : "Calling the Apple Ads Platform API"
}
-->

# Calling the Apple Ads Platform API

Authenticate requests, structure endpoint calls, and interpret responses when using 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](/documentation/Apple-Ads-Platform-API/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:

```console
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](/documentation/Apple-Ads-Platform-API/access-overview) 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:

|Header         |Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
|---------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|`Authorization`|**Required.** The authorization value is always `Bearer`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
|`X-AP-Context` |**Required.** Scopes the request to a specific ad account. Format: `adAccountId={adAccountId}`. Required for all ad-account-scoped operations. **Note:** This isn’t a requirement when calling <doc://com.apple.apple-ads-platform-api/documentation/Apple-Ads-Platform-API/Get-user-ACLs>, <doc://com.apple.apple-ads-platform-api/documentation/Apple-Ads-Platform-API/Get-current-user-details>, <doc://com.apple.apple-ads-platform-api/documentation/Apple-Ads-Platform-API/GET-orgs-_id_>, <doc://com.apple.apple-ads-platform-api/documentation/Apple-Ads-Platform-API/Get-advertiser-resources>, or <doc://com.apple.apple-ads-platform-api/documentation/Apple-Ads-Platform-API/POST-ad-accounts>.|

To return the `userId` and `orgId` of an API caller, use [`Get Me Details`](/documentation/Apple-Ads-Platform-API/Get-current-user-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`](/documentation/Apple-Ads-Platform-API/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:

```json
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:

```json
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.

```json
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](/documentation/Apple-Ads-Platform-API/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](/documentation/Apple-Ads-Platform-API/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**:

|Field       |Type      |Description                                                                                                                                                                                          |
|------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|`filters`   |array     |Filter field conditions. If the request has no filters, the API returns all non-deleted entities within the current ad account scope. It returns deleted entities only when the filters specify them.|
|`sorting`   |array     |Sort entities in ascending or descending order. The default behavior is to sort by ID, ascending.                                                                                                    |
|`pagination`|pagination|Controls pagination settings for results using offset and size.                                                                                                                                      |

The table below details the **filters objects**:

|Field       |Type           |Description                                                                                                                                                                                                                                                                                                                                                                        |
|------------|---------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|`field`     |string         |To filter on a field, use its name (for example, id or name).                                                                                                                                                                                                                                                                                                                      |
|`operator`  |string         |Comparison operator. Supported operators vary by endpoint. See <doc://com.apple.apple-ads-platform-api/documentation/Apple-Ads-Platform-API/QueryFilterOperator> for the full list and per-operator behavior. `IS_NULL` and `IS_NOT_NULL` take no `value`. For case-insensitive matching with any string operator, set `ignoreCase` to `true` instead of using a separate operator.|
|`value`     |scalar or array|One or more filter conditions applied to the result set.                                                                                                                                                                                                                                                                                                                           |
|`ignoreCase`|boolean        |When `true`, the filter comparison is case-insensitive.                                                                                                                                                                                                                                                                                                                            |

The table below details the **sorting objects**:

|Field  |Type  |Description                                                 |
|-------|------|------------------------------------------------------------|
|`field`|string|To sort on a field, use its name (for example, id or name). |
|`order`|string|The sort direction for the specified field: `ASC` or `DESC`.|

The table below details the **request pagination objects**:

|Field            |Type   |Description                                                                                                        |
|-----------------|-------|-------------------------------------------------------------------------------------------------------------------|
|`offset`         |integer|The starting position for pagination.                                                                              |
|`pageSize`       |integer|The number of items per page.                                                                                      |
|`fetchTotalCount`|boolean|When `true`, includes the total count of matching records in the response pagination metadata. Defaults to `false`.|

## Explore the Query Objects

The following objects support querying:

- [`QueryRequest`](/documentation/Apple-Ads-Platform-API/QueryRequest): Drives the query. Contains optional filters, sorting, and pagination.
- [`QueryFilter`](/documentation/Apple-Ads-Platform-API/QueryFilter): A single filter condition. Contains field, operator (see QueryFilterOperator), value, and optional ignoreCase flag.
- [`QueryFilterOperator`](/documentation/Apple-Ads-Platform-API/QueryFilterOperator): The comparison operators supported in query filters.
- [`QuerySort`](/documentation/Apple-Ads-Platform-API/QuerySort): Defines the sort order for a single field. Contains the field and order (see `QuerySortOrder`).
- [`QuerySortOrder`](/documentation/Apple-Ads-Platform-API/QuerySortOrder): The enumeration controlling the sort direction of `ASC` or `DESC`.
- [`QueryPagination`](/documentation/Apple-Ads-Platform-API/QueryPagination): Controls the page size and offset for the result set. Contains `pageSize`, `offset`, and `fetchTotalCount`.
- [`QueryResponse`](/documentation/Apple-Ads-Platform-API/QueryResponse): The paginated response wrapper that contains a paginated result array of entity objects and pagination metadata.
- [`QueryPaginationResult`](/documentation/Apple-Ads-Platform-API/QueryPaginationResult): Reflects the pagination state of the response. Contains `pageSize`, `offset`, and `totalCount`.
- [`Error`](/documentation/Apple-Ads-Platform-API/Error): The top-level error returned when the query fails (for example, an invalid filter field).
- [`ErrorDetail`](/documentation/Apple-Ads-Platform-API/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:

|Field       |Type           |Description                                                   |
|------------|---------------|--------------------------------------------------------------|
|`result`    |object or array|A container for the successful payload when a request succeeds|
|`pagination`|pagination     |Pagination metadata on successful list responses              |
|`error`     |error          |The primary error container                                   |

Some endpoints instead return a dedicated `ErrorResponse` envelope on failure, which wraps a single `error` field containing the `Error` object (see [`Error`](/documentation/Apple-Ads-Platform-API/Error)) rather than embedding `error` alongside `result` and `pagination`. See [`ErrorResponse`](/documentation/Apple-Ads-Platform-API/ErrorResponse) for details.

The response pagination object fields are as follows:

|Field       |Type   |Description                              |
|------------|-------|-----------------------------------------|
|`offset`    |integer|The starting position for pagination     |
|`pageSize`  |integer|The number of items per page             |
|`totalCount`|integer|The total number of items in the response|

The error object fields are as follows:

|Field    |Type              |Description                                                           |
|---------|------------------|----------------------------------------------------------------------|
|`code`   |string            |The reason the API rejected the request                               |
|`message`|string, nullable  |A human-readable error summary of what went wrong at the request level|
|`details`|array[ErrorDetail]|An array of zero or more error details objects                        |

The error detail object fields are as follows:

|Field    |Type            |Description                                                        |
|---------|----------------|-------------------------------------------------------------------|
|`code`   |string          |A granular reason about one part of the error                      |
|`message`|string, nullable|Explicit detail about why the API rejected this part of the request|

**Successful Response**

A successful response example:

```json
{
  "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**:

|HTTP status code|Error message          |Description                                                                |
|----------------|-----------------------|---------------------------------------------------------------------------|
|`400`           |`bad_request`          |The request is malformed or contains invalid parameters.                   |
|`401`           |`unauthorized`         |The token is invalid or expired.                                           |
|`403`           |`forbidden`            |The request requires higher privileges than the access token provides.     |
|`404`           |`not_found`            |The requested resource does not exist.                                     |
|`429`           |`rate_limit_exceeded`  |Too many requests in a short time. Use exponential backoff before retrying.|
|`500`           |`internal_server_error`|An unexpected server-side error occurred.                                  |

A detailed error message example:

```json
{
  "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](/documentation/Apple-Ads-Platform-API/rate-limits) for the full header reference and a sample backoff implementation.

## Topics

### Query Objects

[`QueryRequest`](/documentation/Apple-Ads-Platform-API/QueryRequest)

[`QueryFilter`](/documentation/Apple-Ads-Platform-API/QueryFilter)

[`QuerySort`](/documentation/Apple-Ads-Platform-API/QuerySort)

[`QueryPagination`](/documentation/Apple-Ads-Platform-API/QueryPagination)

[`QueryResponse`](/documentation/Apple-Ads-Platform-API/QueryResponse)

[`QueryPaginationResult`](/documentation/Apple-Ads-Platform-API/QueryPaginationResult)

### Type Aliases

[`QueryFilterOperator`](/documentation/Apple-Ads-Platform-API/QueryFilterOperator)

[`QuerySortOrder`](/documentation/Apple-Ads-Platform-API/QuerySortOrder)

### Response

[`Response`](/documentation/Apple-Ads-Platform-API/Response)

### Error Responses

[`Error`](/documentation/Apple-Ads-Platform-API/Error)

[`ErrorDetail`](/documentation/Apple-Ads-Platform-API/ErrorDetail)

[`ErrorResponse`](/documentation/Apple-Ads-Platform-API/ErrorResponse)


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)