### Example Request for Localized App Details

Source: https://developer.apple.com/documentation/apple_ads/get-localized-app-details

This is an example of a GET request to retrieve localized app details for a specific app.

```bash
GET https://api.searchads.apple.com/api/v5/apps/{adamId}/locale-details        
```

--------------------------------

### Get App Details Request and Response Example

Source: https://developer.apple.com/documentation/apple_ads/get-app-details

Example of the GET request path and the corresponding JSON response payload containing app metadata.

```http
GET https://api.searchads.apple.com/api/v5/apps/{adamId}
```

```json
{
  "data": {
    "id": 284815942,
    "adamId": 284815942,
    "appName": "Trip Trek",
    "artistName": "Trip Trek",
    "primaryLanguage": "en-US",
    "primaryGenre": ">Mobile Software Applications>Utilities",
    "secondaryGenre": ">Mobile Software Applications>Reference",
    "deviceClasses": [
      "IPHONE",
      "IPAD"
    ],
    "iconPictureUrl": "...",
    "isPreOrder": "false",
    "availableStorefronts": [
      "US"
    ]
  }
}
```

--------------------------------

### Get Me Details Request Example

Source: https://developer.apple.com/documentation/apple_ads/get-me-details

Example cURL request including required authorization and context headers.

```bash
curl "https://api.searchads.apple.com/api/v5/me"
-H "Authorization: Bearer {access_token}" \
-H "X-AP-Context: orgId={orgId}"
```

--------------------------------

### Get a Creative Request and Response Example

Source: https://developer.apple.com/documentation/apple_ads/get-a-creative

Example of the GET request path and the corresponding JSON response payload for a creative.

```http
GET https://api.searchads.apple.com/api/v5/creatives/{creativeId}
```

```json
 {
      "id": 94790778,
      "orgId": 42173330,
      "adamId": 918469737,
      "name": "Trip Trek CPP variation 1",
      "type": "CUSTOM_PRODUCT_PAGE",
      "state": "VALID",
      "stateReasons": [],
      "creationTime": "2024-11-08T21:53:35.036",
      "modificationTime": "2024-09-04T21:53:35.036",
      "productPageId": "00d99d1e-ee93-48fc-973e-7ffc0ddfced6"
 }
```

--------------------------------

### Get a Budget Order Payload Example

Source: https://developer.apple.com/documentation/apple_ads/get-a-budget-order

An example request URL and the corresponding JSON response structure for a budget order.

```http
GET https://api.searchads.apple.com/api/v5/budgetorders/{boId}
```

```json
{
  "data": {
    "orgIds": [
      3761812
    ],
    "bo": {
      "id": 542370539,
      "name": "get a budget order example",
      "startDate": "2024-04-08T00:00:00.000",
      "endDate": "2024-04-09T23:59:59.999",
      "budget": {
        "amount": "2000",
        "currency": "USD"
      },
      "orderNumber": "2376542",
      "clientName": "Trip Trek",
      "primaryBuyerName": "Trip Trek",
      "primaryBuyerEmail": "buyer@triptrek.com",
      "billingEmail": "billing@triptrek.com",
      "status": "COMPLETED",
      "parentOrgId": 27154130,
      "supplySources": [
        "APPSTORE_PRODUCT_PAGES_BROWSE", 
        "APPSTORE_SEARCH_RESULTS",
        "APPSTORE_SEARCH_TAB", 
        "APPSTORE_TODAY_TAB"
      ]
    }
  },
  "pagination": null,
  "error": null
}
```

--------------------------------

### Example Request for Multiple Countries

Source: https://developer.apple.com/documentation/apple_ads/get-supported-countries-or-regions

Example GET request to retrieve supported countries or regions for multiple specified countries (US, AU, GB, CA).

```http
GET https://api.searchads.apple.com/api/v5/countries-or-regions?countriesOrRegions=US,AU,GB,CA
```

--------------------------------

### Get a Targeting Keyword Payload Example

Source: https://developer.apple.com/documentation/apple_ads/get-a-targeting-keyword-in-an-ad-group

Example request and response for fetching a targeting keyword.

```http
GET https://api.searchads.apple.com/api/v5/campaigns/{campaignId}/adgroups/{adgroupId}/targetingkeywords/{keywordId}
```

```json
{
  "id": 542370642,
  "adGroupId": 427916203,
  "text": "targeting keyword example 1",
  "status": "ACTIVE",
  "matchType": "BROAD",
  "bidAmount": {
    "amount": "100",
    "currency": "USD"
  },
  "modificationTime": "2025-04-08T20:48:28.206",
  "deleted": false
}
```

--------------------------------

### Get Product Page Locales Payload Example

Source: https://developer.apple.com/documentation/apple_ads/get-product-page-locales

An example request URL and the corresponding JSON response structure for product page locales.

```http
GET https://api.searchads.apple.com/api/v5/apps/{adamId}/product-pages/{productPageId}/locale-details
```

```json
{
  "adamId": 1408851466,
  "productPageId": "45812c9b-c296-43d3-c6a0-c5a02f74bf6e0",
  "language": "en",
  "appName": "Trip Trek",
  "languageCode": "en-US",
  "subTitle": "Updated for iOS 15",
  "promotionalText": "The best travel app for iOS.",
  "shortDescription": "A cartographic dashboard to track your awesome treks.",
  "deviceClasses": [
    "IPHONE"
  ]
}
```

--------------------------------

### Example Request for a Single Country

Source: https://developer.apple.com/documentation/apple_ads/get-supported-countries-or-regions

Example GET request to retrieve supported countries or regions for a single specified country (CA).

```http
GET https://api.searchads.apple.com/api/v5/countries-or-regions?countriesOrRegions=CA
```

--------------------------------

### Create an Ad Payload Example

Source: https://developer.apple.com/documentation/apple_ads/create-an-ad

Example request and response payloads for creating an ad.

```http
POST https://api.searchads.apple.com/api/v5/campaigns/{campaignId}/adgroups/{adgroupId}/ads


{
  "creativeId": 94895512,
  "name": "Trip Trek custom product page variation",
  "status": "ENABLED"
}
```

```json
{
  "id": 573408745,
  "orgId": 39872140,
  "campaignId": 570798765,
  "adGroupId": 427916203,
  "creativeId": 94895512,
  "name": "Trip Trek custom product page variation",
  "creativeType": "CUSTOM_PRODUCT_PAGE",
  "status": "ENABLED",
  "servingStatus": "RUNNING",
  "statusReasons": [],
  "deleted": false,
  "creationTime": "2024-10-09 21:25:33",
  "modificationTime": "2024-10-09 21:25:33"
}
```

--------------------------------

### API GET Request with Pagination

Source: https://developer.apple.com/documentation/apple_ads/pagination

Example of a GET request to retrieve campaigns, using limit and offset query parameters to control the number of returned results.

```http
GET https://api.searchads.apple.com/api/v5/campaigns?limit=<LIMIT>&offset=<OFFSET>
```

--------------------------------

### Get All Ads Payload Example

Source: https://developer.apple.com/documentation/apple_ads/get-all-ads

This is an example of the JSON payload returned when successfully fetching all ads for an ad group. It includes details about each ad.

```json
{
    "id": 573408745,
    "orgId": 39872140,
    "campaignId": 570798765,
    "adGroupId": 570798765,
    "creativeId": 94895512,
    "name": "Trip Trek custom product page variation",
    "creativeType": "CUSTOM_PRODUCT_PAGE",
    "status": "PAUSED",
    "servingStatus": "NOT_RUNNING",
    "servingStateReasons": [
      "PAUSED_BY_USER"
      ],
    "deleted": false,
    "creationTime": "2024-10-08T00:18:37.606Z",
    "modificationTime": "2024-10-09T00:18:37.606Z"
}
```

--------------------------------

### Example Payload for Get All Campaign Negative Keywords

Source: https://developer.apple.com/documentation/apple_ads/get-all-campaign-negative-keywords

This is an example of the JSON response when successfully retrieving a list of negative keywords for a campaign. Each object represents a negative keyword with its associated details.

```json
[
        {
            "id": 542370642,
            "campaignId": 542370539,
            "adGroupId": 427916203,
            "text": "Get campaign negative keyword example 1",
            "status": "ACTIVE",
            "matchType": "BROAD",
            "modificationTime": "2024-04-08T17:48:31.979",
            "deleted": false
        },
        {
            "id": 542370643,
            "campaignId": 542370539,
            "adGroupId": 427916203,
            "text": "Get campaign negative keyword example 2",
            "status": "ACTIVE",
            "matchType": "EXACT",
            "modificationTime": "2024-04-08T17:48:31.984",
            "deleted": false
        },
        {
            "id": 542370644,
            "campaignId": 542370539,
            "adGroupId": 427916203,
            "text": "Get campaign negative keyword example 3",
            "status": "ACTIVE",
            "matchType": "EXACT",
            "modificationTime": "2024-04-08T20:52:59.050",
            "deleted": false
        },
        {
            "id": 542370645,
            "campaignId": 542370539,
            "adGroupId": 427916203,
            "text": "Get campaign negative keyword example 4",
            "status": "ACTIVE",
            "matchType": "BROAD",
            "modificationTime": "2024-04-08T20:52:59.054",
            "deleted": false
        }
    ]
```

--------------------------------

### GET /api/v5/campaigns

Source: https://developer.apple.com/documentation/apple_ads/calling-the-apple-search-ads-api

Example request to the Apple Ads Campaign Management API demonstrating required headers.

```APIDOC
## GET /api/v5/campaigns

### Description
Fetches campaign data from the Apple Ads API. Requires authorization and organization context.

### Method
GET

### Endpoint
https://api.searchads.apple.com/api/v5/campaigns

### Parameters
#### Request Headers
- **Authorization** (string) - Required - The authorization value, must be 'Bearer {access_token}'.
- **X-AP-Context** (string) - Required - The value is your 'orgId'.
```

--------------------------------

### Find App Eligibility Records Payload Example

Source: https://developer.apple.com/documentation/apple_ads/find-app-eligibility-records

Example request and response payloads for querying app eligibility.

```json
POST https://api.searchads.apple.com/api/v5/apps/<adamId>/eligibilities/find


{
    "conditions": [
        {
            "field": "countryOrRegion",
            "operator": "IN",
            "values": ["US", "MX"]
        },
        {
            "field": "supplySource",
            "operator": "EQUALS",
            "values": ["APPSTORE_TODAY_TAB"]
        }
    ],
    "pagination": {
        "offset": 0,
        "limit": 2
    }
}
```

```json
{
    "data": [
        {
            "adamId": 123456789,
            "deviceClass": "IPHONE",
            "state": "ELIGIBLE",
            "minAge": 18,
            "countryOrRegion": "US",
            "supplySource": "APPSTORE_TODAY_TAB"
        },
        {
            "adamId": 123456789,
            "deviceClass": "IPAD",
            "state": "INELIGIBLE",
            "minAge": 18,
            "countryOrRegion": "US",
            "supplySource": "APPSTORE_TODAY_TAB"
        }
    ],
    "pagination": {
        "totalResults": 4,
        "startIndex": 0,
        "itemsPerPage": 2
    }
}
```

--------------------------------

### JWT Header Example

Source: https://developer.apple.com/documentation/apple_ads/implementing-oauth-for-the-apple-search-ads-api

An example of a JWT header, specifying the signing algorithm and key ID.

```json
{
"alg": "ES256",
"kid": "d136aa66-0c3b-4bd4-9892-c20e8db024ab"
}
```

--------------------------------

### Get a Targeting Keyword in a Maximize Conversions Campaign

Source: https://developer.apple.com/documentation/apple_ads/get-a-targeting-keyword-in-an-ad-group

Example request and response for a targeting keyword within a Maximize Conversions campaign context.

```http
GET https://api.searchads.apple.com/api/v5/campaigns/{campaignId}/adgroups/{adgroupId}/targetingkeywords/{keywordId}
```

```json
{
  "id": 542370642,
  "campaignId": 585885088,
  "adGroupId": 542370539,
  "text": "food delivery",
  "status": "ACTIVE",
  "matchType": "BROAD",
  "bidAmount": {
    "amount": "0",
    "currency": "USD"
  }
  ...
}
```

--------------------------------

### Example Age Range Inclusion

Source: https://developer.apple.com/documentation/apple_ads/agecriteria

Example of how to include a specific age range (20-25) within the 'included' property of age targeting criteria.

```json
"age": {
      "included": [
        {
          "minAge": 20,
          "maxAge": 25
        }
      ]
    },
```

--------------------------------

### Get an Ad Group Payload Example

Source: https://developer.apple.com/documentation/apple_ads/get-an-ad-group

An example of the GET request and the corresponding JSON response body for an ad group.

```http
GET https://api.searchads.apple.com/api/v5/campaigns/{campaignId}/adgroups/{adgroupId}
```

```json
{
    "id": 542370539,
    "campaignId": 56543219,
    "name": " ad group name example",
    "cpaGoal": {
      "amount": "100",
      "currency": "USD"
    },
    "startTime": "2025-04-08T12:00:22.788",
    "endTime": "2025-04-09T12:00:22.788",
    "automatedKeywordsOptIn": false,
    "defaultBidAmount": {
      "amount": "100",
      "currency": "USD"
    },
   "pricingModel": "CPC",    
   "targetingDimensions": {
      "age": {
        "included": [
          {
            "minAge": 20,
            "maxAge": 25
          },
          {
            "minAge": 25,
            "maxAge": 55
          }
        ]
      },
      "gender": {
        "included": [
          "M",
          "F"
        ]
      },
      "country": null,
      "adminArea": null,
      "locality": null,
      "deviceClass": {
        "included": [
          "IPAD",
          "IPHONE"
        ]
      },
      "daypart": {
        "userTime": {
          "included": [
            1,
            3,
            22
          ]
        }
      },
      "appDownloaders": null
    },
    "orgId": 40669820,
    "modificationTime": "2025-04-08T19:00:24.105",
    "status": "ENABLED",
    "servingStatus": "RUNNING",
    "servingStateReasons": null,
    "displayStatus": "RUNNING",
    "deleted": false
}
```

--------------------------------

### App Preview Device Mapping Example

Source: https://developer.apple.com/documentation/apple_ads/apppreviewdevicesmappingresponse/data-data.dictionary

Provides an example of the key-value pairs for app preview device sizes. The key is the device identifier, and the value is the display name. This can also define supported fallback devices.

```json
{
  "ipadPro": "iPad 12.9",
  "iphone6+": "iPhone 5.5",
  "iphone_5_8": "iPhone 5.8",
  "iphone5": "iPhone 4",
  "iphone6": "iPhone 4.7",
  "ipadPro_2018": "iPad 11",
  "ipad": "iPad 9.7",
  "iphone_6_5": "iPhone 6.5",
  "ipad_10_5": "iPad 10.5"
}
```

--------------------------------

### Get User ACL Example Request and Response

Source: https://developer.apple.com/documentation/apple_ads/get-user-acl

Example request and the corresponding JSON response structure for the Get User ACL call.

```HTTP
GET https://api.searchads.apple.com/api/v5/acls
```

```JSON
{
  "data": {
    "orgName": "Trip Trek",
    "orgId": 40669820,
    "currency": "USD",
    "timeZone": "America/Los_Angeles",
    "paymentModel": "PAYG",
    "roleNames": [
      "Admin"
    ],
    "parentOrgId": "27154130",
    "displayName": "Trip Trek"
  },
  "pagination": null,
  "error": null
}
```

--------------------------------

### Example Daypart Configuration

Source: https://developer.apple.com/documentation/apple_ads/daypartdetail

Shows the JSON structure for configuring daypart targeting using the included property.

```json
"daypart": {
      "userTime": {
        "included": [
          1,
          3,
          22
        ]
      }
    }
```

--------------------------------

### Create a Campaign

Source: https://developer.apple.com/documentation/apple_ads/using-apple-search-ads-api-functionality

This example demonstrates how to create a new campaign using a POST request. It includes the necessary fields for campaign creation, such as organization ID, ad channel type, budget, and target countries.

```APIDOC
## POST /api/v5/campaigns

### Description
Creates a new campaign resource.

### Method
POST

### Endpoint
/api/v5/campaigns

### Request Body
- **orgId** (integer) - Required - The organization ID.
- **adChannelType** (string) - Required - The type of ad channel (e.g., "SEARCH").
- **supplySources** (array) - Required - The supply sources for the ads (e.g., ["APPSTORE_SEARCH_RESULTS"]).
- **billingEvent** (string) - Required - The billing event type (e.g., "TAPS").
- **name** (string) - Required - The name of the campaign.
- **dailyBudgetAmount** (object) - Required - The daily budget for the campaign.
  - **amount** (string) - Required - The budget amount.
  - **currency** (string) - Required - The currency of the budget.
- **adamId** (integer) - Required - The Apple ID of the app.
- **countriesOrRegions** (array) - Required - A list of countries or regions for the campaign.

### Request Example
```json
{
    "orgId": 40669820,
    "adChannelType": "SEARCH",
    "supplySources": ["APPSTORE_SEARCH_RESULTS"],
    "billingEvent": "TAPS",  
    "name": "campaign 1",
    "dailyBudgetAmount": {
        "amount": "300", 
        "currency": "USD"
     },
    "adamId": 427916203,
    "countriesOrRegions": ["US","AU"]
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the created campaign details.
  - **id** (integer) - The unique identifier for the created campaign.
  - **orgId** (integer) - The organization ID.
  - **name** (string) - The name of the campaign.
  - **dailyBudgetAmount** (object) - The daily budget details.
    - **amount** (string) - The budget amount.
    - **currency** (string) - The currency of the budget.
  - **adamId** (integer) - The Apple ID of the app.
  - **paymentModel** (string) - The payment model.
  - **budgetOrders** (array) - List of budget orders.
  - **displayStatus** (string) - The display status of the campaign.
  - **adChannelType** (string) - The ad channel type.
  - **supplySources** (array) - The supply sources.
  - **billingEvent** (string) - The billing event type.
  - **startTime** (string) - The start time of the campaign.
  - **endTime** (string) - The end time of the campaign.
  - **status** (string) - The status of the campaign.
  - **servingStatus** (string) - The serving status.
  - **servingStateReasons** (array) - Reasons for the serving state.
  - **modificationTime** (string) - The modification time.
  - **deleted** (boolean) - Indicates if the campaign is deleted.
  - **sapinLawResponse** (string) - The SAPIN law response.
  - **countriesOrRegions** (array) - The countries or regions.
  - **countryOrRegionServingStateReasons** (object) - Serving state reasons by country or region.
- **pagination** (null) - Pagination details (null for this operation).
- **error** (null) - Error details (null if successful).

#### Response Example
```json
{
    "data": {
        "id": 542317095,
        "orgId": 40669820,
        "name": "example campaign",
        "dailyBudgetAmount": {
            "amount": "300",
            "currency": "USD"
        },
        "adamId": 427916203,
        "paymentModel": "PAYG",
        "locInvoiceDetails": null,
        "budgetOrders": [],
        "displayStatus": "ON_HOLD",
        "adChannelType": "SEARCH",
        "supplySources": ["APPSTORE_SEARCH_RESULTS"],
        "billingEvent": "TAPS",  
        "startTime": "2024-04-08T10:33:31.650",
        "endTime": "2024-04-09T10:33:31.650",
        "status": "ENABLED",
        "servingStatus": "NOT_RUNNING",
        "servingStateReasons": [
            "AD_GROUP_MISSING"
        ],
        "modificationTime": "2024-04-08T18:21:35.133",
        "deleted": false,
        "sapinLawResponse": "NOT_ANSWERED",
        "countriesOrRegions": [
            "AU",
            "US"
        ],
        "countryOrRegionServingStateReasons": {}
    },
    "pagination": null,
    "error": null
}
```
```

--------------------------------

### Update Budget Order Response Example

Source: https://developer.apple.com/documentation/apple_ads/update-a-budget-order

This example shows a successful response when updating a budget order. It includes the updated budget order information, such as its ID, status, and other details.

```json
{
  "data": {
    "orgIds": [
      40669820
    ],
    "bo": {
      "id": 542370539,
      "name": "update a budget order example",
      "startDate": "2024-03-04T23:25:06.973Z",
      "endDate": "2024-03-04T23:25:06.973Z",
      "budget": {
        "amount": "400",
        "currency": "USD"
      },
      "orderNumber": "34562212",
      "clientName": "Trip Trek",
      "primaryBuyerName": "Trip Trek",
      "primaryBuyerEmail": "admin@triptrek.com",
      "billingEmail": "billing@triptrek.com",
      "status": "ACTIVE",
      "parentOrgId": 27154130,
      "supplySources": [
        "APPSTORE_SEARCH_RESULTS"
      ]
    }
  },
  "pagination": null,
  "error": null
}
```

--------------------------------

### Example Payload: Search for iOS Apps

Source: https://developer.apple.com/documentation/apple_ads/search-for-ios-apps

A sample request and its corresponding JSON response when searching for iOS apps. This example shows the structure of the returned app information.

```http
GET https://api.searchads.apple.com/api/v5/search/apps?query=apple&limit=1
```

```json
[
  {
    "adamId": 427916203,
    "appName": "Trip Trek example app",
    "developerName": "example Apple developer",
    "countryOrRegionCodes": [
      "FR",
      "DE",
      "US",
      "NO",
      "MX",
      "GB",
      "CA",
      "SE",
      "AU"
    ]
  }
]
```

--------------------------------

### App Asset List Response Example

Source: https://developer.apple.com/documentation/apple_ads/find-app-assets

This is an example of a successful response from the Find App Assets endpoint, containing a list of app assets and pagination details.

```json
{
  "data": [
    {
      "assetGenId": "368234568;en-US;9;0;4201c5a4bd4087cc82xdfetdc8141b94d0",
      "adamId": 835599320,
      "assetURL”: “https://is5-ssl.mzstatic.com/image/thumb/source113/v4/25/f5/70/25f57023-87bd-25f0-71dc-bf5f48525b4c/afcd3ec4-d7af-49c5-9d93-44084b0abea8_2208x1242iphone55_4.jpg/2208x1242.jpg",
      "assetVideoURL": null,
      "appPreviewDevice": “iphone_6_7”,
      "sourceHeight": 2208,
      "sourceWidth": 1242,
      "orientation": "PORTRAIT",
      "assetType": "SCREENSHOT"
    },
    {
      "assetGenId": "368234568;en-US;9;0;4201c5a4bd4087cc82xdfetdc8141b94d0",
      "adamId": 835599320,
      "assetURL”: “https://is5-ssl.mzstatic.com/image/thumb/PurpleSource122/v4/0b/d2/ea/0bd2ea96-744a-4341-2227-8aaa5c79ceef/84589e4f-d770-4444-9ade-e0806658f171_0.png/1290x2796.jpg",
      "assetVideoURL": null,
      "appPreviewDevice": "iphone_6_7",
      "sourceHeight": 1290,
      "sourceWidth": 2796,
      "orientation": “LANDSCAPE”,
      "assetType": “SCREENSHOT”
    }
 ],
  "pagination": {
    "totalResults": 2,
    "startIndex": 0,
    "itemsPerPage": 10
  }
}
```

--------------------------------

### Update Campaign - Switch to Manual Bid Strategy

Source: https://developer.apple.com/documentation/apple_ads/update-a-campaign

This example shows switching from a Maximize Conversions bid strategy to a manual bid strategy. It also details setting the 'TargetCpa' to null.

```APIDOC
## PUT https://api.searchads.apple.com/api/v5/campaigns/{campaignId}

### Description
Updates a campaign's bidding strategy. This example demonstrates switching from 'MAX_CONVERSIONS' to a 'MANUAL_CPT' bid strategy and setting 'TargetCpa' to null.

### Method
PUT

### Endpoint
https://api.searchads.apple.com/api/v5/campaigns/{campaignId}

### Parameters
#### Path Parameters
- **campaignId** (integer) - Required - The ID of the campaign to update.

#### Request Body
- **clearGeoTargetingOnCountryOrRegionChange** (boolean) - Optional - If true, clears existing geo-targeting when country or region is changed.
- **campaign** (object) - Required - Contains campaign update details.
  - **biddingStrategy** (string) - Required - The bidding strategy to set. Example: "MANUAL_CPT".
  - **targetCpa** (null) - Required to be null when switching to a manual bid strategy.

### Request Example
```json
{
  "clearGeoTargetingOnCountryOrRegionChange": false,
  "campaign": {
    "biddingStrategy": "MANUAL_CPT",
    "targetCpa": null
  }
}
```

### Response
#### Success Response (200)
- **id** (integer) - The campaign ID.
- **orgId** (integer) - The organization ID.
- **name** (string) - The campaign name.
- **dailyBudgetAmount** (object) - The daily budget amount.
  - **amount** (string) - The budget amount.
  - **currency** (string) - The currency of the budget.
- **adamId** (integer) - The App Store ID.
- **paymentModel** (string) - The payment model.
- **locInvoiceDetails** (null) - Placeholder for location invoice details.
- **budgetOrders** (array) - List of budget orders.
- **billingEvent** (string) - The billing event type.
- **supplySources** (array) - List of supply sources.
- **biddingStrategy** (string) - The current bidding strategy.
- **targetCpa** (null) - Target CPA is null for manual strategies.
- **adChannelType** (string) - The ad channel type.
- **displayStatus** (string) - The display status of the campaign.
- **startTime** (string) - The start time of the campaign.
- **endTime** (string) - The end time of the campaign.
- **status** (string) - The status of the campaign.
- **servingStatus** (string) - The serving status of the campaign.
- **servingStateReasons** (null) - Reasons for the serving state.
- **modificationTime** (string) - The last modification time.
- **deleted** (boolean) - Indicates if the campaign is deleted.
- **sapinLawResponse** (string) - Response related to SAPIN law.
- **countriesOrRegions** (array) - List of countries or regions targeted.
- **countryOrRegionServingStateReasons** (object) - Reasons for country or region serving state.

#### Response Example
```json
{
  "id": 542370642,
  "orgId": 40669820,
  "name": "TripTrek campaign 2",
  "dailyBudgetAmount": {
    "amount": "500",
    "currency": "USD"
  },
  "adamId": 427916203,
  "paymentModel": "PAYG",
  "locInvoiceDetails": null,
  "budgetOrders": [],
  "billingEvent": "TAPS",
  "supplySources": [
    "APPSTORE_SEARCH_RESULTS"
  ],
  "biddingStrategy": "MANUAL_CPT",
  "targetCpa": null,
  "adChannelType": "SEARCH",
  "displayStatus": "RUNNING",
  "startTime": "2025-05-18T00:00:00.000",
  "endTime": "2025-05-22T00:00:00.000",
  "status": "ENABLED",
  "servingStatus": "RUNNING",
  "servingStateReasons": null,
  "modificationTime": "2025-05-08T18:27:56.380",
  "deleted": false,
  "sapinLawResponse": "NOT_ANSWERED",
  "countriesOrRegions": [
    "AU",
    "CA",
    "GB",
    "US"
  ],
  "countryOrRegionServingStateReasons": {}
}
```
```

--------------------------------

### Localized App Details Response Example

Source: https://developer.apple.com/documentation/apple_ads/get-localized-app-details

This JSON object represents the successful response when fetching localized app details. It includes app name, description, and asset information.

```json
{
  "data": [
    {
      "language": "en-US",
      "appName": "Trip Trek",
      "shortDescription": "Trip Trek app.",
      "isPrimaryLocale": true,
      "subTitle": "Search for trips.",
      "appPreviewDeviceWithAssets": {
        "ipadPro": {
          "appPreviewDeviceFallBackDevices": null,
          "screenshots": [
            {
              "assetGenId": "…",
              "assetToken": "…",
              "assetUrl": "…",
              "appPreviewDevice": "…",
              "sortPosition": 1,
              "sourceHeight": 2732,
              "sourceWidth": 2048,
              "orientation": "PORTRAIT",
              "assetType": "SCREENSHOT",
              "checksum": "…",
              "pictureUrl": "…",
              "videoUrl": null,
              "assetDuplicationType": null
            }
          ],
          "appPreviews": null
        }
      }
    }
  ]
}
```

--------------------------------

### Example Selector for Finding Campaigns

Source: https://developer.apple.com/documentation/apple_ads/selector

This example demonstrates how to use a Selector object to filter returned records for campaigns. It specifies fields to return, conditions for serving status, sorting order, and pagination limits.

```json
POST https://api.searchads.apple.com/api/v5/campaigns/find


{
  "fields": [
    "id",
    "name",
    "adamId",
    "dailyBudgetAmount",
    "status",
    "servingStatus"
  ],
  "conditions": [
    {
      "field": "servingStatus",
      "operator": "IN",
      "values": [
        "NOT_RUNNING"
      ]
    }
  ],
  "orderBy": [
    {
      "field": "id",
      "sortOrder": "DESCENDING"
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 10
  }
}



```

--------------------------------

### Get All Creatives Payload Example

Source: https://developer.apple.com/documentation/apple_ads/get-all-creatives

This is an example of the JSON payload returned when successfully fetching creative objects. It includes details such as ID, organization ID, Adam ID, name, type, state, and timestamps.

```json
{
  "id": 94790778,
  "orgId": 42173330,
  "adamId": 918469737,
  "name": "Trip Trek CPP variation 1",
  "type": "CUSTOM_PRODUCT_PAGE",
  "state": "VALID",
  "stateReasons": [],
  "creationTime": "2024-11-08T21:53:35.036",
  "modificationTime": "2024-09-04T21:53:35.036",
  "productPageId": "00d99d1e-ee93-48fc-973e-7ffc0ddfced6"
}
```

--------------------------------

### Get Me Details Response Example

Source: https://developer.apple.com/documentation/apple_ads/get-me-details

The JSON response structure containing the caller's userId and parentOrgId.

```json
{
  "data": {
    "userId": 3962840,
    "parentOrgId": 27154130
  }
}
```

--------------------------------

### App Preview Device Sizes Payload Example

Source: https://developer.apple.com/documentation/apple_ads/get-app-preview-device-sizes

This is an example of the JSON payload returned when successfully fetching app preview device sizes. It maps internal device identifiers to user-facing display names.

```json
{
    "ipadPro": "iPad 12.9",
    "iphone6+": "iPhone 5.5",
    "iphone_5_8": "iPhone 5.8",
    "iphone5": "iPhone 4",
    "iphone6": "iPhone 4.7",
    "ipadPro_2018": "iPad 11",
    "ipad": "iPad 9.7",
    "iphone_6_5": "iPhone 6.5",
    "ipad_10_5": "iPad 10.5"
}
```

--------------------------------

### Return Totals Configuration

Source: https://developer.apple.com/documentation/apple_ads/reportingrequest

Example configuration for `returnRowTotals` and `returnGrandTotals` when `granularity` is set to `DAILY`.

```json
"granularity": "DAILY",
"returnRowTotals": false,
"returnGrandTotals": false
```

--------------------------------

### Get all Budget Orders Response Payload

Source: https://developer.apple.com/documentation/apple_ads/get-all-budget-orders

This is an example of a successful response when fetching all budget orders. It includes budget order details and pagination information.

```json
{
  "data": [
    {
      "orgIds": [
        3761812
      ],
      "bo": {
        "id": 542370539,
        "name": "get all budget orders example",
        "startDate": “2024-04-08T00:00:00.000”,
        "endDate": “2024-04-09T23:59:59.999",
        "budget": {
          "amount": "2000",
          "currency": "USD"
        },
        "orderNumber": "2376542",
        "clientName": "Trip Trek",
        "primaryBuyerName": "Trip Trek",
        "primaryBuyerEmail": "buyer@triptrek.com",
        "billingEmail": "billing@triptrek.com",
        "status": "COMPLETED",
        "parentOrgId": 27154130,
        "supplySources": [
          "APPSTORE_SEARCH_RESULTS"
          "APPSTORE_PRODUCT_PAGES_BROWSE", 
          "APPSTORE_SEARCH_TAB", 
          "APPSTORE_TODAY_TAB"
        ]
      }
    }
  ],
  "pagination": null,
  "error": null
}
```

--------------------------------

### Get Campaign Negative Keyword Payload Example

Source: https://developer.apple.com/documentation/apple_ads/get-a-campaign-negative-keyword

This is an example of the JSON payload returned when successfully fetching a campaign negative keyword. It includes details like ID, campaign ID, ad group ID, text, status, match type, modification time, and deletion status.

```json
{
  "id": 542370642,
  "campaignId": 542370539,
  "adGroupId": 542317095,
  "text": "Get campaign negative keywords example",
  "status": "ACTIVE",
  "matchType": "BROAD",
  "modificationTime": "2024-04-08T17:48:31.979",
  "deleted": false
}
```

--------------------------------

### Response Example for Keyword-Level Reports

Source: https://developer.apple.com/documentation/apple_ads/get-keyword-level-within-ad-group-reports

A sample JSON response body containing keyword performance metrics and metadata.

```json
{
    "row": [
      {
        "other": false,
        "total": {
        "impressions": 53,
        "taps": 45,
        "ttr": 0.45,
        "avgCPT": {
          "amount": "0",
          "currency": "USD"
        },
        "avgCPM": {
          "amount": "0",
          "currency": "USD"
        },
        "localSpend": {
          "amount": "0",
          "currency":"USD"
        },
        "totalInstalls": 16,
        "totalNewDownloads": 23,
        "totalRedownloads": 17,
        "viewInstalls": 18,
        "tapInstalls": 59,
        "tapNewDownloads": 22,
        "tapRedownloads": 35,
        "viewNewDownloads": 67,
        "viewReDownloads": 53,
        "tapPreOrdersPlaced": 0,
        "viewPreOrdersPlaced": 0,
        "totalPreOrdersPlaced": 0,
        "totalAvgCPI": {
           "amount": "1.57",
           "currency": "USD"
           },
        "totalInstallRate": 2.962
        "tapInstallCPI": {
          "amount": "0",
          "currency": “USD”
        },
       "tapInstallRate": 0.7654,
       "date": "2024-05-08"
      },
         "metadata": {
          "keywordId": 87675432,
          "keyword": "keyword 1",
          "keywordStatus": "ACTIVE",
          "matchType": "BROAD",
          "bidAmount": {
            "amount": "100",
            "currency": "USD"
          },
          "deleted": false,
          "keywordDisplayStatus": "RUNNING",
          "adGroupId": 542317095,
          "adGroupName": "Ad Group 1",
          "adGroupDeleted": false,
          "modificationTime": "2024-04-08T09:33:45.387"
        },
        "insights": {
          "bidRecommendation": {
            "bidMin": {
              "amount": "null",
              "currency": "null"
            },
            "bidMax": {
              "amount": "400",
              "currency": "USD"
           },
          "suggestedBidAmount": {
            "amount": "2.40",
            "currency": "USD"
             }
        }
      }
    }
  ]
}
```

--------------------------------

### Example Credentials for Client Secret

Source: https://developer.apple.com/documentation/apple_ads/implementing-oauth-for-the-apple-search-ads-api

Display of clientId, teamId, and keyId obtained after uploading a public key. These are necessary for creating a client secret.

```text
clientId SEARCHADS.aeb3ef5f-0c5a-4f2a-99c8-fca83f25a9
teamId SEARCHADS.hgw3ef3p-0w7a-8a2n-77c8-scv83f25a7
keyId a273d0d3-4d9e-458c-a173-0db8619ca7d7

```

--------------------------------

### Partial Fetch for Campaigns

Source: https://developer.apple.com/documentation/apple_ads/using-apple-search-ads-api-functionality

Use the `fields` query parameter with GET endpoints to limit the properties returned in a response. This example shows how to fetch only the `id`, `name`, and `countriesOrRegions` for campaigns.

```HTTP
GET https://api.searchads.apple.com/api/v5/campaigns?fields=id,name,countriesOrRegions
```

```JSON
{
    "data": [
        {
            "id": 542370539,
            "name": "Multicountry campaign example 1",
            "countriesOrRegions": [
                "FR"
            ]
        },
        {
            "id": 542370549,
            "name": "Multicountry campaign example 2",
            "countriesOrRegions": [
                "GB"
            ]
        },
        {
            "id": 542370559,
            "name": "Multicountry campaign example 3",
            "countriesOrRegions": [
                "CA",
                "JP",
                "NZ",
                "AU"
            ]
        }
    ],
    "pagination": {
        "totalResults": 3,
        "startIndex": 0,
        "itemsPerPage": 20
    },
    "error": null
}
```

--------------------------------

### Example Selector for Archived Campaigns

Source: https://developer.apple.com/documentation/apple_ads/selector

This example shows how to use a Selector object to retrieve both deleted and undeleted resources, such as archived campaigns. It sets conditions to include deleted resources and specifies sorting and pagination.

```json
{
  "fields": null,
  "conditions": [
    {
      "field": "deleted",
      "operator": "IN",
      "values": [
        true,
        false
      ]
    }
  ],
  "orderBy": [
    {
      "field": "name",
      "sortOrder": "ASCENDING"
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 100
  }
}


```

--------------------------------

### PageDetail JSON Response Example

Source: https://developer.apple.com/documentation/apple_ads/pagedetail

Example structure of a response containing the pagination object.

```json
{
   "data":[
     { },
     ...
   ],
   "pagination"{
     "totalResults": 10,
     "startIndex": 1,
     "itemsPerPage": 10
   },
}
```

--------------------------------

### Campaign Creation POST Response

Source: https://developer.apple.com/documentation/apple_ads/using-apple-search-ads-api-functionality

This is an example response after successfully creating a campaign. The `id` returned in the `data` object is crucial for subsequent calls targeting this specific campaign.

```json
{
    "data": {
        "id": 542317095,
        "orgId": 40669820,
        "name": "example campaign",
        "dailyBudgetAmount": {
            "amount": "300",
            "currency": "USD"
        },
        "adamId": 427916203,
        "paymentModel": "PAYG",
        "locInvoiceDetails": null,
        "budgetOrders": [],
        "displayStatus": "ON_HOLD",
        "adChannelType": "SEARCH",
        "supplySources": ["APPSTORE_SEARCH_RESULTS"],
        "billingEvent": "TAPS",  
        "startTime": "2024-04-08T10:33:31.650",
        "endTime": "2024-04-09T10:33:31.650",
        "status": "ENABLED",
        "servingStatus": "NOT_RUNNING",
        "servingStateReasons": [
            "AD_GROUP_MISSING"
        ],
        "modificationTime": "2024-04-08T18:21:35.133",
        "deleted": false,
        "sapinLawResponse": "NOT_ANSWERED",
        "countriesOrRegions": [
            "AU",
            "US"
        ],
        "countryOrRegionServingStateReasons": {}
    },
    "pagination": null,
    "error": null
}
```

--------------------------------

### AgeRange Request Example

Source: https://developer.apple.com/documentation/apple_ads/agerange

Example of how to include the AgeRange object in an ad targeting request.

```APIDOC
```json
{
  "age": {
    "included": [
      {
        "minAge": 20,
        "maxAge": 25
      }
    ]
  }
}
```
```

--------------------------------

### JWT Payload Example

Source: https://developer.apple.com/documentation/apple_ads/implementing-oauth-for-the-apple-search-ads-api

An example of a JWT payload, including issuer, audience, timestamps, and subject.

```json
{
"iss": "SEARCHADS.9703f56c-10ce-4876-8f59-e78e5e23a152",
"iat": 2234567891,
"exp": 2234567900,
"aud": "https://appleid.apple.com",
"sub": "SEARCHADS.9703f56c-10ce-4876-8f59-e78e5e23a152"
}
```

--------------------------------

### Example Campaign Object

Source: https://developer.apple.com/documentation/apple_ads/update-a-campaign

This is an example of the JSON object representing a campaign's current state after an update or when fetched. It includes details such as ID, name, budget, and targeting information.

```json
{
  "id": 542370642,
  "orgId": 40669820,
  "name": "TripTrek campaign 2",
  "dailyBudgetAmount": {
    "amount": "500",
    "currency": "USD"
  },
  "adamId": 427916203,
  "paymentModel": "PAYG",
  "locInvoiceDetails": null,
  "budgetOrders": [],
  "billingEvent": "TAPS",
  "supplySources": [
    "APPSTORE_SEARCH_RESULTS"
  ],
  "adChannelType": "SEARCH",
  "displayStatus": "RUNNING",
  "startTime": "2025-05-18T00:00:00.000",
  "endTime": "2025-05-22T00:00:00.000",
  "status": "ENABLED",
  "servingStatus": "RUNNING",
  "servingStateReasons": null,
  "modificationTime": "2025-05-08T18:27:56.380",
  "deleted": false,
  "sapinLawResponse": "NOT_ANSWERED",
  "countriesOrRegions": [
    "AU",
    "CA",
    "GB",
    "US"
  ],
  "countryOrRegionServingStateReasons": {}
}
```