### Example User Agent String Source: https://ads-api.reddit.com/docs/v3/ratelimits/Leads An example of a correctly formatted user agent string for an Android application. ```text User-Agent: android:com.example.myredditapp:v1.2.3 (by /u/kemitche) ``` -------------------------------- ### Create App Installs Campaign (Non-CBO) Source: https://ads-api.reddit.com/docs/v3/set-up-a-campaign Use this JSON structure to create an App Installs campaign without Campaign Budget Optimization (CBO). You must provide the 'app_id' for your app. Tip: Use `Get SKAdNetwork Availability` to check your remaining SKAdNetwork ID quota. ```json { "data": { "name": "{{Name in Ads Manager}}", "configured_status": "{{Entity status}}", "objective": "APP_INSTALLS", "is_campaign_budget_optimization": false, "app_id": "{{App or Play Store App ID}}" } } ``` -------------------------------- ### Example Response with Preview URL Source: https://ads-api.reddit.com/docs/v3/preview-an-ad This is an example response from the API that includes the `preview_expiry` and `preview_url` for an ad. ```json { "data": { "id": "2150528811614587268", "...": "...", "preview_expiry": "2025-11-14T15:32:29.080868+00:00", "preview_url": "https://www.reddit.com/?ad=kR9wTqLzP5hA3cVnE7sGbUjM8fXyB6dK4aW2oP1iL0uYvJmQzR7tW5sF9eG1cHkO8rB3xNlD4pG6jVbCqI2gA9uYhTfE7lK5zM0wR8oPvB4cQ%3D", "...": "..." } } ``` -------------------------------- ### Example Authorization URL Source: https://ads-api.reddit.com/docs/v3/authenticate-your-developer-application An example of a fully constructed authorization URL with sample credentials and parameters. Use this as a reference when creating your own authorization links. ```text https://www.reddit.com/api/v1/authorize?client_id=DnvSjQYG9t13lWWOndNqOg&response_type=code&state=4f8d7c1b9a2e6d3c5b0f7a1e8c2d9b6a&redirect_uri=https://www.reddit.com/prefs/apps&duration=permanent&scope=adsconversions ``` -------------------------------- ### Get Business Response Example Source: https://ads-api.reddit.com/docs/v3/operations/Get%20Business This is an example of a successful JSON response when retrieving business details. It includes information such as the business ID, name, country, industry, and creation/modification timestamps. ```json { "data": { "agency_affiliated": true, "country": "CA", "created_at": "2023-03-27T21:18:39Z", "creator_id": "t2_example", "id": "1e200a0b-4e98-32cc-dd47-3006e4c85bb2", "industry": "RETAIL_AND_ECOMMERCE", "modified_at": "2023-03-27T21:18:39Z", "name": "Reddit Inc.", "phone": "+1-123-456-7890", "primary_contact_id": "t2_example", "website_url": "https://www.redditinc.com/" } } ``` -------------------------------- ### List Creative Assets Response Example Source: https://ads-api.reddit.com/docs/v3/operations/List%20Creative%20Assets Example JSON response for listing creative assets, including asset details and pagination information. ```json { "data": [ { "result": { "id": "t2_1234567890-IMAGE-232", "name": "string", "type": "IMAGE", "status": "DELETED", "source": "USER", "errors": [ { "field": "media", "message": "The image you provided is too small." } ], "media": { "permanent_url": "string", "mime_type": "image/jpeg", "height": 1080, "width": 1920, "aspect_ratio": "4:3" } } } ], "pagination": { "next_url": "https://ads-api.reddit.com/api/v3?page.token=nextToken", "previous_url": "https://ads-api.reddit.com/api/v3?page.token=previousToken" } } ``` -------------------------------- ### Successful Response Example Source: https://ads-api.reddit.com/docs/v3/operations/Post%20Conversion%20Events This is an example of a successful response when posting conversion events. ```json { "data": { "message": "Successfully processed 3 conversion events." } } ``` -------------------------------- ### Example App ID Source: https://ads-api.reddit.com/docs/v3/operations/Create%20Ad%20Group Example of an app ID for the Apple App Store or Google Play Store, used for APP_INSTALLS campaigns. ```text 1064216828com.reddit.frontpage ``` -------------------------------- ### Feature Access Response Example Source: https://ads-api.reddit.com/docs/v3/operations/Get%20Feature%20Access This is an example of a successful JSON response when retrieving feature access. It includes the data and pagination details. ```json { "data": [ { "name": "reddit_max", "source": "ACL" } ], "pagination": { "next_url": "https://ads-api.reddit.com/api/v3?page.token=nextToken", "previous_url": "https://ads-api.reddit.com/api/v3?page.token=previousToken" } } ``` -------------------------------- ### Ad Group Creation Example Source: https://ads-api.reddit.com/docs/v3/operations/Create%20Ad%20Group This example demonstrates the structure of a request body for creating an ad group, including comprehensive targeting, bidding, and optimization settings. ```json { "data": { "bid_type": "CPC", "bid_value": 500000, "campaign_id": "579922433862993631", "configured_status": "ACTIVE", "effective_status": "ACTIVE", "end_time": "2019-02-18T22:27:10Z", "goal_type": "DAILY_SPEND", "goal_value": 75, "name": "string", "optimization_goal": "ADD_TO_CART", "start_time": "2019-02-18T22:27:10Z", "targeting": { "carriers": [ "ATT_WIRELESS_US" ], "communities": [ "aww" ], "custom_audience_ids": [ "67547345732543" ], "devices": [ { "label_map": { "Samsung": [ "Galaxy S9", "Galaxy S10+" ] }, "max_version": "9", "min_version": "14", "os": "ANDROID", "type": "DESKTOP" } ], "excluded_communities": [ "politics" ], "excluded_custom_audience_ids": [ "95423594327534" ], "excluded_geolocations": [ "US", "3852263", "CA:6167865" ], "excluded_interests": [ "entertainment" ], "excluded_keywords": [ "alcohol", "drugs" ], "expand_targeting": true, "gender": "FEMALE", "geolocations": [ "US", "CA:6167865" ], "interests": [ "entertainment" ], "keywords": [ "apple", "computer" ], "locations": [ "FEED" ], "platforms": [ "DESKTOP" ], "suppression_event_types": [ "ALL_FEATURES" ], "view_modes": [ "CARD" ], "languages": [ "EN" ] }, "view_through_conversion_type": "SEVEN_DAY_CLICKS", "conversion_pixel_id": "t2_123456", "app_id": "1064216828", "bid_strategy": "BIDLESS", "optimization_strategy_type": "DOWNSTREAM_CONVERSIONS", "product_set_id": "ebb0698a-fef2-4373-ae75-8ec44ba4d037", "saved_audience_id": "1216949373062893780", "schedule": [ { "end_day": 5, "end_hour": 7, "start_day": 1, "start_hour": 10 } ], "shopping_targeting": { "conversion_event_types": [ "VIEW_CONTENT", "SEARCH" ], "excluded_conversion_event_types": [ "VIEW_CONTENT" ], "lookback_window_days": 90, "targeting_type": "PROSPECTING" }, "shopping_type": "DYNAMIC", "skadnetwork_metadata": { "status": "ENABLED" } } } ``` -------------------------------- ### Example Product Set ID Source: https://ads-api.reddit.com/docs/v3/operations/Create%20Ad%20Group Example of a product set ID for an ad group. Required for CATALOG_SALES ads and used for dynamic product ads. ```text ebb0698a-fef2-4373-ae75-8ec44ba4d037 ``` -------------------------------- ### List Pixels Response Example Source: https://ads-api.reddit.com/docs/v3/operations/List%20Pixels%20By%20Business This is an example JSON response when successfully retrieving a list of pixels for a business. It includes pixel details and pagination information. ```json { "data": [ { "business_id": "1e200a0b-4e98-32cc-dd47-3006e4c85bb2", "id": "1234567890", "name": "Snoo's Pixel", "created_at": "2023-03-27T21:18:39Z", "created_by": "1234567890", "modified_at": "2023-03-27T21:18:39Z", "modified_by": "1234567890", "automatic_matching_config": { "collect_email": true, "collect_phone_number": true }, "enhanced_signal_collection_config": { "collect_page_metadata": true } } ], "pagination": { "next_url": "https://ads-api.reddit.com/api/v3?page.token=nextToken", "previous_url": "https://ads-api.reddit.com/api/v3?page.token=previousToken" } } ``` -------------------------------- ### Report Response Example Source: https://ads-api.reddit.com/docs/v3/operations/Get%20A%20Report This is an example of a successful response when requesting a report. It includes the requested metrics, the last updated time for these metrics, and pagination details. ```json { "data": { "metrics": [ { "campaign_id": "1822122159046060063", "impressions": 50000, "ecpm": 0.5, "clicks": 100, "cpc": 0.1, "ctr": 0.2 } ], "metrics_updated_at": "2023-11-14T21:50:54.167000+00:00" }, "pagination": { "next_url": "https://ads-api.reddit.com/api/v3?page.token=nextToken", "previous_url": "https://ads-api.reddit.com/api/v3?page.token=previousToken", "page_index": 0, "total_count": 150 } } ``` -------------------------------- ### Response Body Example Source: https://ads-api.reddit.com/docs/v3/operations/Get%20Me This is an example of the JSON response body you can expect when successfully retrieving the authenticated user's data. It includes various profile fields. ```json { "data": { "type": "MEMBER", "email": "john.snoo@reddit.com", "firstname": "John", "id": "1234567890", "lastname": "Snoo", "phone": "+1-123-456-7890", "reddit_user_id": "t2_123456", "reddit_username": "reddit_user" } } ``` -------------------------------- ### Conversions Campaign Setup Source: https://ads-api.reddit.com/docs/v3/set-up-a-campaign Configure a campaign for conversions. The 'optimization_goal' must match a tracked event or be set to 'CLICKS' if the Pixel is not fully set up. ```json { "data": { "bid_strategy": "{{Bid strategy}}", "bid_type": "CPM", "start_time": "{{Start delivery}}", "goal_value": {{Goal value (micros)}}, "bid_value": {{Bid value (micros)}}, "campaign_id": "{{Campaign ID}}", "optimization_goal": "{{Optimization goal}}", "view_through_conversion_type": "SEVEN_DAY_CLICKS_ONE_DAY_VIEW", "configured_status": "{{Entity status}}", "name": "{{Name in Ads Manager}}", "conversion_pixel_id": "{{Pixel ID}}" } } ``` -------------------------------- ### Create Product Set Response Source: https://ads-api.reddit.com/docs/v3/operations/Create%20Product%20Set Example of a successful response when creating a product set, including its details and summary. ```json { "data": { "id": "00000000-0000-0000-0000-000000000000", "catalog_id": "00000000-0000-0000-0000-000000000000", "name": "My awesome products", "filter": "string", "summary": { "products_count": 42, "approved_products_count": 39, "rejected_products_count": 3, "issues": { "critical": { "IMAGE_PROCESSING_ERROR": 3 }, "warning": { "INVALID_GOOGLE_CATEGORY": 1 } }, "invalid_products_count": 1 }, "created_at": "2023-03-27T21:18:39Z", "modified_at": "2023-03-27T21:18:39Z" } } ``` -------------------------------- ### Get Last Fired At Response Example Source: https://ads-api.reddit.com/docs/v3/operations/Get%20Last%20Fired%20At This JSON response shows the structure of data returned by the 'Get Last Fired At' endpoint. It includes timestamps for standard conversion events like 'add_to_cart', 'purchase', and 'lead', as well as custom events. ```JSON { "data": { "add_to_cart": "2023-11-06T00:00:00+00:00", "add_to_wishlist": "2023-11-06T00:00:00+00:00", "breakdown": { "SubscribeHere": "2023-11-06T00:00:00+00:00" }, "custom": "2023-11-06T00:00:00+00:00", "custom_events": [ { "last_fired_at": "2023-11-06T00:00:00+00:00", "name": "SubscribeHere" } ], "lead": "2023-11-06T00:00:00+00:00", "page_visit": "2023-11-06T00:00:00+00:00", "purchase": "2023-11-06T00:00:00+00:00", "search": "2023-11-06T00:00:00+00:00", "sign_up": "2023-11-06T00:00:00+00:00", "view_content": "2023-11-06T00:00:00+00:00" } } ``` -------------------------------- ### Creative Asset Response Example Source: https://ads-api.reddit.com/docs/v3/operations/Get%20Creative%20Asset This is a sample JSON response for a successful request to get a creative asset. It includes details about the asset's properties, status, and media information. ```json { "data": { "id": "t2_1234567890-IMAGE-232", "name": "string", "type": "IMAGE", "status": "DELETED", "source": "USER", "errors": [ { "field": "media", "message": "The image you provided is too small." } ], "media": { "permanent_url": "string", "mime_type": "image/jpeg", "height": 1080, "width": 1920, "aspect_ratio": "4:3" } } } ``` -------------------------------- ### Get App Last Fired At - Response Example Source: https://ads-api.reddit.com/docs/v3/operations/Get%20App%20Last%20Fired%20At This JSON response shows the last time various conversion events fired for a given app. The timestamps are in ISO 8601 format. ```json { "data": { "mobile_conversion_ad_click": "2023-11-06T00:00:00+00:00", "mobile_conversion_ad_view": "2023-11-06T00:00:00+00:00", "mobile_conversion_add_payment_info": "2023-11-06T00:00:00+00:00", "mobile_conversion_add_to_cart": "2023-11-06T00:00:00+00:00", "mobile_conversion_add_to_wishlist": "2023-11-06T00:00:00+00:00", "mobile_conversion_app_launch": "2023-11-06T00:00:00+00:00", "mobile_conversion_checkout": "2023-11-06T00:00:00+00:00", "mobile_conversion_completed_tutorial": "2023-11-06T00:00:00+00:00", "mobile_conversion_first_time_purchase": "2023-11-06T00:00:00+00:00", "mobile_conversion_install": "2023-11-06T00:00:00+00:00", "mobile_conversion_level_achieved": "2023-11-06T00:00:00+00:00", "mobile_conversion_login": "2023-11-06T00:00:00+00:00", "mobile_conversion_onboard_completed": "2023-11-06T00:00:00+00:00", "mobile_conversion_onboard_started": "2023-11-06T00:00:00+00:00", "mobile_conversion_purchase": "2023-11-06T00:00:00+00:00", "mobile_conversion_rate": "2023-11-06T00:00:00+00:00", "mobile_conversion_reinstall": "2023-11-06T00:00:00+00:00", "mobile_conversion_search": "2023-11-06T00:00:00+00:00", "mobile_conversion_sign_up": "2023-11-06T00:00:00+00:00", "mobile_conversion_spend_credits": "2023-11-06T00:00:00+00:00", "mobile_conversion_start_trial": "2023-11-06T00:00:00+00:00", "mobile_conversion_subscribe": "2023-11-06T00:00:00+00:00", "mobile_conversion_unlock_achievement": "2023-11-06T00:00:00+00:00", "mobile_conversion_view_content": "2023-11-06T00:00:00+00:00" } } ``` -------------------------------- ### List Devices Response Example Source: https://ads-api.reddit.com/docs/v3/operations/List%20Devices This is an example of a successful JSON response when listing devices. It includes a 'data' array with device details (model and make) and a 'pagination' object with URLs for navigating through results. ```JSON { "data": [ { "model": "Iphone 12", "make": "Apple" } ], "pagination": { "next_url": "https://ads-api.reddit.com/api/v3?page.token=nextToken", "previous_url": "https://ads-api.reddit.com/api/v3?page.token=previousToken" } } ``` -------------------------------- ### iOS Campaign Setup Source: https://ads-api.reddit.com/docs/v3/set-up-a-campaign Use this JSON structure to set up a campaign targeting iOS devices. Ensure the 'min_version' is correctly specified. ```json { "data": { "bid_strategy": "{{Bid strategy}}", "bid_type": "CPM", "start_time": "{{Start delivery}}", "goal_value": {{Goal value (micros)}}, "bid_value": {{Bid value (micros)}}, "campaign_id": "{{Campaign ID}}", "configured_status": "{{Entity status}}", "name": "{{Name in Ads Manager}}", "optimization_goal": "{{Optimization goal}}", "conversion_pixel_id": "{{Pixel ID}}", "targeting": { "devices": [ { "type": "MOBILE", "os": "IOS", "min_version": "{{≥14}}" } ], "platforms": [Platform] } } } ``` -------------------------------- ### List Posts Request Example Source: https://ads-api.reddit.com/docs/v3/operations/List%20Posts This cURL command demonstrates how to make a GET request to the List Posts endpoint. Ensure you replace `{profile_id}` with the actual profile ID and provide a valid OAuth 2.0 token. ```curl curl --request GET \ --url https://ads-api.reddit.com/api/v3/profiles/{profile_id}/posts \ --header 'Accept: application/json' \ --header 'Authorization: Bearer 123' ``` -------------------------------- ### Hashing Phone Number Example Source: https://ads-api.reddit.com/docs/v3/capi-direct-integration Illustrates the canonicalization and hashing of a phone number. The number must include country and area codes, have extensions removed, all non-numeric characters stripped, and start with '+', before SHA-256 hashing. ```text +15554441234 and +1 (555) 444-1234 should both hash to e5b124c58580eb16bd959b8d0cac12b12c952e2ceae0203d416cff94f10b994a ``` -------------------------------- ### Video Views Campaign Setup Source: https://ads-api.reddit.com/docs/v3/set-up-a-campaign JSON structure for setting up a campaign optimized for video views. ```json { "data": { "bid_strategy": "{{Bid strategy}}", "bid_type": "CPV6", "start_time": "{{Start delivery}}", "goal_value": {{Goal value (micros)}}, "bid_value": {{Bid value (micros)}}, "campaign_id": "{{Campaign ID}}", "configured_status": "{{Entity status}}", "name": "{{Name in Ads Manager}}", "optimization_goal": "{{Optimization goal}}", "conversion_pixel_id": "{{Pixel ID}}" } } ``` -------------------------------- ### Catalog Sales (Dynamic) Campaign Setup Source: https://ads-api.reddit.com/docs/v3/set-up-a-campaign Configure dynamic catalog sales campaigns. Includes 'shopping_targeting' with 'lookback_window_days' and 'targeting_type'. ```json { "data": { "bid_strategy": "{{Bid strategy}}", "bid_type": "CPC", "start_time": "{{Start delivery}}", "goal_value": {{Goal value (micros)}}, "bid_value": {{Bid value (micros)}}, "campaign_id": "{{Campaign ID}}", "product_set_id": "{{Product set ID}}", "view_through_conversion_type": "SEVEN_DAY_CLICKS_ONE_DAY_VIEW", "optimization_goal": "{{Optimization goal}}", "configured_status": "{{Entity status}}", "name": "{{Name in Ads Manager}}", "shopping_type": "DYNAMIC", "shopping_targeting": { "lookback_window_days": {{Lookback window days}}, "targeting_type": "{{Shopping targeting type}}" }, "conversion_pixel_id": "{{Pixel ID}}" } } ``` -------------------------------- ### Example Saved Audience ID Source: https://ads-api.reddit.com/docs/v3/operations/Create%20Ad%20Group Example of a saved audience ID for an ad group. ```text 1216949373062893780 ``` -------------------------------- ### Catalog Sales (Static) Campaign Setup Source: https://ads-api.reddit.com/docs/v3/set-up-a-campaign Use this JSON for static catalog sales campaigns. Ensure 'product_set_id' is provided. ```json { "data": { "bid_strategy": "{{Bid strategy}}", "bid_type": "CPC", "start_time": "{{Start delivery}}", "goal_value": {{Goal value (micros)}}, "bid_value": {{Bid value (micros)}}, "campaign_id": "{{Campaign ID}}", "product_set_id": "{{Product set ID}}", "view_through_conversion_type": "SEVEN_DAY_CLICKS_ONE_DAY_VIEW", "optimization_goal": "{{Optimization goal}}", "configured_status": "{{Entity status}}", "name": "{{Name in Ads Manager}}", "shopping_type": "STATIC", "conversion_pixel_id": "{{Pixel ID}}" } } ``` -------------------------------- ### Build Standard Ad Source: https://ads-api.reddit.com/docs/v3/set-up-a-campaign Use this structure to create a standard ad. For app install campaigns, set 'click_url' to your app's store product URL. ```json { "data": { "ad_group_id": "{{Ad group ID}}", "name": "{{Ad name}}", "post_id": "{{Post ID (legacy t3_…)}}", "click_url": "{{Click URL (landing page)}}", "configured_status": "{{Entity status}}" } } ``` -------------------------------- ### Example Shopping Targeting Type Source: https://ads-api.reddit.com/docs/v3/operations/Create%20Ad%20Group Example of the type of ads an ad group should contain for shopping ads. ```text STATIC ``` -------------------------------- ### Get Structured Post Source: https://ads-api.reddit.com/docs/v3/operations/List%20Structured%20Posts Retrieves a specific structured post by its ID. This operation is available via a GET request. ```APIDOC ## GET /structured-posts/{post_id} ### Description Retrieves a specific structured post by its ID. ### Method GET ### Endpoint /structured-posts/{post_id} ### Parameters #### Path Parameters - **post_id** (string) - Required - The ID of the structured post. ### Response #### Success Response (200) - **id** (string) - The ID of the post. - **title** (string) - The title of the post. - **content** (object) - The content of the post. - **created_time** (integer) - The creation timestamp of the post. ### Response Example { "id": "post_123", "title": "Example Structured Post", "content": { "type": "text", "text": "This is the content of the post." }, "created_time": 1678886400 } ``` -------------------------------- ### RateLimit-Policy Header Example Source: https://ads-api.reddit.com/docs/v3/capi-error-handling This header provides the application rate limit policies for the requested route, including policy name, quota, and window. ```text RateLimit-Policy: "custom-audience-ingestion";q=3000;w=900,"custom-audience-ingestion-burst";q=500;w=60 ``` -------------------------------- ### Create Product Catalog Source: https://ads-api.reddit.com/docs/v3/catalog-setup Use this endpoint to create a new product catalog. Ensure you provide a unique name, default language, default currency, and event sources. ```json { "data": { "name": "My awesome catalog", "default_language": "en", "default_currency": "USD", "event_sources": [ "a2_xxxxxxxxxxxx" ] } } ``` -------------------------------- ### Awareness Campaign Setup Source: https://ads-api.reddit.com/docs/v3/set-up-a-campaign JSON structure for setting up a campaign optimized for awareness. ```json { "data": { "bid_strategy": "{{Bid strategy}}", "bid_type": "CPM", "start_time": "{{Start delivery}}", "goal_value": {{Goal value (micros)}}, "bid_value": {{Bid value (micros)}}, "campaign_id": "{{Campaign ID}}", "configured_status": "{{Entity status}}", "name": "{{Name in Ads Manager}}", "conversion_pixel_id": "{{Pixel ID}}" } } ``` -------------------------------- ### Hashing External ID Example Source: https://ads-api.reddit.com/docs/v3/capi-direct-integration Provides an example of an unhashed and a hashed external ID. External IDs are advertiser-assigned custom identifiers. ```text Example (unhashed): customer12345 ``` ```text Example (hashed): a4cc2fc5adf58a029291c1514d273989113a1d05e1d753c1d0c3a848af7109cc ``` -------------------------------- ### List Interests Response Example Source: https://ads-api.reddit.com/docs/v3/operations/List%20Interests This is an example of a successful JSON response when listing targeting interests. It includes the category, ID, and name for each interest. ```JSON { "data": [ { "category": "Animals & Pets", "id": "animals_v2", "name": "Animals" } ] } ``` -------------------------------- ### Create Product Catalog cURL Request Source: https://ads-api.reddit.com/docs/v3/operations/Create%20Product%20Catalog Example of how to make a POST request to create a product catalog using cURL. Ensure to replace placeholders with your actual business ID and authorization token. ```curl curl --request POST \ --url https://ads-api.reddit.com/api/v3/businesses/{business_id}/product_catalogs \ --header 'Accept: application/json' \ --header 'Authorization: Bearer 123' \ --header 'Content-Type: application/json' \ --data '{ \ "data": { \ "name": "My awesome catalog", \ "default_language": "en", \ "default_currency": "USD", \ "event_sources": [ \ "a2_xxxxxxxxxxxx" \ ] \ } \ }' ``` -------------------------------- ### Industry Response Example Source: https://ads-api.reddit.com/docs/v3/operations/List%20Industries This is an example of a successful JSON response when listing industries. It contains an array of industry objects, each with an 'id' and 'display' name. ```JSON { "data": [ { "id": "RETAIL_AND_ECOMMERCE", "display": "Retail & eCommerce" } ] } ```