--- agentTools: projectIndex: https://docs.developer.yelp.com/llms.txt --- # Ads API > ⚠️ Documentation Disclaimer > > This documentation is not exhaustive and does not guarantee system behavior. Integrators are responsible for testing against actual API responses. See [Documentation Disclaimer](https://docs.developer.yelp.com/docs/documentation-disclaimer) for full details. > πŸ“˜ This is a Yelp Partner API > > Access is disabled by default. See [Yelp Partner APIs](https://docs.developer.yelp.com/docs/yelp-partner-apis) on how to get access. # Overview This page is the primary reference for the Yelp Ads API endpoints, parameters, and error codes. The API provides a means to create, modify, and terminate advertising programs for businesses on Yelp. Access is not available by default β€” to request access, work with your Yelp account team. ## Table of Contents * [Before You Build](#before-you-build) * [Authentication](#authentication) * [Versioning](#versioning) * [Format & Value Types](#format--value-types) * [Yelp Business IDs](#yelp-business-ids) * [Advertising API Endpoints](#advertising-api-endpoints) * [Create Program](#create-program) * [Modify Program](#modify-program) * [Terminate Program](#terminate-program) * [Receipting (Job Status)](#receipting) * [Pause Program](#pause-program) * [Resume Program](#resume-program) * [Advertising API Errors](#advertising-api-errors) * [Error Codes](#error-codes) * [Error Messages](#error-messages) *** ## Before You Build The following pages cover integration guidance, behavioral nuances, and reference material that go beyond what is documented on this page. Review them before building your integration. | Page | What it covers | | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | [Ads API Onboarding Guide](https://docs.developer.yelp.com/docs/getting-started-with-the-ads-api) | How to get test credentials, what to test, and how to request live access | | [Campaign Management Behavior & Nuances](https://docs.developer.yelp.com/docs/campaign-management-behavior-nuances) | Non-obvious behavioral facts: feature carryover, SCT limitations, async gotchas, promo lifecycle | | [Async Job Processing & Error Handling](https://docs.developer.yelp.com/docs/async-job-processing-error-handling) | Polling pattern, terminal states, PARENT\_WAS\_REJECTED debugging, full error code reference | | [Program Features Reference](https://docs.developer.yelp.com/docs/program-features-reference) | All configurable features: SCT, CLT, ad scheduling, ad goal, link tracking, call tracking | | [Budget & Billing Reference](https://docs.developer.yelp.com/docs/budget-billing-reference) | Budget formatting (cents), fee periods, proration, over-delivery, budget change behavior | | [Enhanced Profiles & CTAs](https://docs.developer.yelp.com/docs/enhanced-profiles-ctas) | EP lifecycle, CTA configuration, detecting existing EP, EP vs CPC differences | | [Reporting & Metrics Reference](https://docs.developer.yelp.com/docs/reporting-metrics-reference) | Metric definitions, billed vs delivered clicks, data availability windows | | [FAQs](https://docs.developer.yelp.com/docs/ads-faqs) | Common questions on ad creation, billing, promos, geotargeting, and more | *** ## Authentication Authentication uses basic HTTP authentication over SSL. The credentials used for the Yelp Data Ingestion API should be used for the Advertising API. ## Versioning To maintain backwards-compatibility with partner-developed applications, the Yelp Advertising API is versioned with the version encoded in the URI. The current and latest version is v1 and all endpoints are located at . ## Format & Value Types Response bodies use the content type and should be encoded in UTF-8. All date properties should use the format. ## Identifiers Yelp identifiers are unique within a type of object only β€” they are not globally unique. For example, a photo and business may share the same identifier, but no other photo or business will have that same identifier. ## Yelp Business IDs The Advertising API requires encrypted business IDs to create new programs. Please reference our [Business Match API documentation](https://www.yelp.com/developers/documentation/v3/business_match) on how to pull these values for Yelp listings. *** # Advertising API Endpoints The Yelp Advertising API provides a means to add/modify/terminate advertising programs for businesses on Yelp by calling into one of the following four endpoints: | Method | HTTP Request | Description | | :------------ | :----------------------- | :------------------------------------------------ | | **create** | POST /create | Create a new program for a Yelp business | | **modify** | POST /{program\_id}/edit | Modify an existing program for a Yelp business | | **terminate** | POST /{program\_id}/end | Terminate an existing program for a Yelp business | | **status** | GET /status/{job\_id} | Obtain the status of an existing ingestion job | ## Create Program ### HTTP POST **Request:** ```javascript curl \ -X POST \ --user "{username}:{password}" \ https://partner-api.yelp.com/v1/reseller/program/create?start=&end=&business_id=&program_name= ``` **Description:** This endpoint will create the program `` to the Yelp business as specified by ``. Start and end dates are left as optional parameters to specify the duration of the program. The dates are expected to be in YYYY-MM-DD format. `` and `` are the required parameters for all program types. For CPC programs, `` and `` is required. The `` parameter is also required for CPC programs if `` is set to false. **NOTE:** For CPC programs, the business listing **must have** text for the specialties field since CPC ads uses text from specialties if there isn't a sufficient level of reviews to use reviews text for ads. Please use the Data Ingestion API to set the about\_this\_business\_specialties field for a given business. Also, the business listing **must have** at least 1 category in order to appear in Yelp search results. **Common Program Parameters: (create)**
\ The following table describes the request parameters for all programs. [block:html] { "html": "\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n \n \n \n \n \n \n \n \n \n\n \n
Property NameValueOptionalDescription
business_idstringNoYelp business id
program_namestringNoIndicates the type of program you want to enable.

\n Possible values are:\n
    \n
  • BP – Branded Profile
    • \n
  • EP – Enhanced Profile
    • \n
  • CPC – Cost per click ads
    • \n
  • RCA (Remove Competitor Ads)
    • \n
  • CTA (Call To Action)
    • \n
  • SLIDESHOW (Slideshow)
    • \n
  • BH (Business Highlights)
    • \n
  • VL (Verified License)
    • \n
  • LOGO
    • \n
  • PORTFOLIO
    • \n
\n
promotion_codestringYesUse a valid promotion code to purchase this program.
startdateYesStart date for the specified program. The date format is YYYY-MM-DD format (e.g., 2016-01-01). Programs will start at 12:00am PST for a given start date.

If no start date is set, then the program will start immediately.
enddateYesEnd date for the specified program. The date format is YYYY-MM-DD format (e.g., 2016-01-31). Programs will end at 11:59pm PST for a given end date.\n

\nIf no end date is set, then the program will run indefinitely until it is terminated via the Advertising API.\n
" } [/block] **CPC Program Parameters: (create)**\
The following table describes the request parameters for CPC programs. [block:html] { "html": "\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n\n \n \n \n \n \n \n \n \n \n\n \n \n \n \n \n \n \n \n \n \n \n\n \n \n \n \n \n \n \n
Property NameValueOptionalDescription
budgetintegerNoMonthly budget in cents. For a monthly budget of $50.00, please input β€œ5000”.
Value must be greater than or equal to $25 dollars.
currencystringYesISO 4217 Currency Code. Default is USD
is_autobidbooleanNoIf field is set to true, then Yelp will autobid. Set to false if using max_bid\n
max_bidintegerYes*Maximum bid value in cents.
\n* Value must be greater than or equal to $0.50 or \"50\".
\n* This field is required if is_autobid is false.
\n* You can set a max_bid for paced campaigns but will run the risk of potentially underfulfilling if the max_bid is set too low.
\n* If you want to bid a maximum of $25.50, please use a value of β€œ2550” cents and not β€œ25.50” which will result in error.\n* max_bid is not immediately applied and can take up to 24 hours to go live on Yelp's end.
\n\n
pacing methodstringYesPossible values are:\n
\n * \"paced\" (default if is_autobid=true)
\n * \"unpaced\" (default if max_bid is set) - cannot be used if is_autobid=true.

\n\n\"paced\" will attempt to spread the budget evenly throughout the month.
\n\"unpaced\" will attempt to spend the budget as fast as possible.

\n Please reach out to partner-support@yelp.com if you're interested in using unpaced campaigns before using that setting.
\n \n
fee_periodstringYes\nPossible values are:
\n* CALENDAR_MONTH
\n* ROLLING_MONTH

\n\nThe fee_period determines the time frame for the CPC Program. If CALENDAR_MONTH, then budgets will reset at the 1st of every month. If ROLLING_MONTH, then budgets will reset every 30 days. Default is CALENDAR_MONTH.\n
\n ad_categories\n \n list of strings\n \n Yes\n \n You are able to choose any of the categories of the specified business and run the CPC campaign for only these categories.\n\t\t

\nYou get the categories of a business using the Get business by ID endpoint.\n
Use the alias of the categories (field categories[].alias).\n

\nExample: If the business has the categories hvac and plumbing, you can run two different campaigns for each category with a different budget each.\n
" } [/block] **Usage Example for creating CPC program with $200.00 budget and maximum bid of $5.00 starting on Jan 1, 2016 and ending on Jan 31, 2016:** **Example Request:** ```javascript curl \ -X POST \ --user "{username}:{password}" \ https://partner-api.yelp.com/v1/reseller/program/create?business_id=WavvLdfdP6g8aZTtbBQHTw&program_name=CPC&budget=20000&max_bid=500&is_autobid=false&start=2016-01-01&end=2016-01-31 ``` **Example Response:** ```javascript Response: { "job_id": "prvtN-nilb4mUynGGgKuBQ" } ``` See Receipting for responses after completion of the request **Usage Example for adding Branded Profile program that starts immediately:** **Example Request:** ```javascript curl \ --user "{username}:{password}" \ -X POST \ https://partner-api.yelp.com/v1/reseller/program/create?business_id=WavvLdfdP6g8aZTtbBQHTw&program_name=BP ``` **Example Response:** ```javascript Response: { "job_id": "prvtN-nilb4mUynGGgKuBQ" } ``` See Receipting for responses after completion of the request **Usage Example for adding Enhanced Profile program that starts immediately:** **Example Request:** ```javascript curl \ --user "{username}:{password}" \ -X POST \ https://partner-api.yelp.com/v1/reseller/program/create?business_id=WavvLdfdP6g8aZTtbBQHTw&program_name=EP ``` **Example Response:** ```javascript Response: { "job_id": "prvtN-nilb4mUynGGgKuBQ" } ``` See Receipting for responses after completion of the request ## Modify Program ### HTTP POST **Request:** ```javascript curl \ -X POST \ --user "{username}:{password}" \ https://partner-api.yelp.com/v1/reseller/program//edit?start=&end= ``` **Description:** This endpoint will allow modification to attributes of an existing program, \. This endpoint will be incapable of setting the end date to be a date in the past, or modifying the start date of a program that has already started, or modifying the start date to be before the current time. Programs will end at the end of day of the end date. **Common Program Parameters: (edit)**

\ The following table describes the request parameters for all programs. [block:html] { "html": "\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n\n\n \n \n \n \n \n \n \n \n \n\n \n
Property NameValueOptionalDescription
program_idstringNoThe program_id that needs to be modified.
startdateYesStart date for the specified program\n
enddateYesEnd date for the specified program\n
\n
" } [/block] **CPC Program Parameters: (edit)**
\ The following table describes the request parameters for CPC programs. [block:html] { "html": "\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n\n \n \n \n \n \n \n \n \n \n\n \n \n \n \n \n \n \n
Property NameValueOptionalDescription
budgetintegerYesMonthly budget in cents.
future_budget_datedateYesSchedule an upcoming budget change for campaign.
max_bidintegerYesMaximum bid value in cents. Can only be changed if program is using max_bid option. * The minimum value is $0.50 which is \"50\"\n
pacing_methodstringYes\nPossible values are:
\n* \"paced\"
\n* \"unpaced\"
\n\n
\n ad_categories\n \n list of strings\n \n Yes\n \n You are able to choose any of the categories of the specified business and run the CPC campaign for only these categories.\n\t\t

\nYou get the categories of a business using the Get business by ID endpoint.\n
Use the alias of the categories (field categories[].alias).\n

\nExample: If the business has the categories hvac and plumbing, you can run two different campaigns for each category with a different budget each.\n
" } [/block] **Usage Example for modifying budget to $250.00 and maximum bid to $10.00:** **Example Request:** ```javascript curl \ --user "{username}:{password}" \ -X POST \ https://partner-api.yelp.com/v1/reseller/program/c6HT44PKCaXqzN_BdgKPCw/edit?budget=25000&max_bid=1000 ``` **Example Response:** ```javascript Response: { "job_id": "yf8sGfL9NNRpHoXmKudBwg" } ``` See sample request & response when viewing status of a job id for a modified program: **Example Request:** ```javascript curl \ -X GET \ -H "Accept: application/json" \ --user "{username}:{password}" \ https://partner-api.yelp.com/v1/reseller/status/yf8sGfL9NNRpHoXmKudBwg ``` **Response Format:** 
{
  "status": "COMPLETED",
  "completed_at": {datetime},
  "created_at": {datetime}>,
  "business_results": [
    {
      "status": "COMPLETED",
      "identifier_type": "PROGRAM",
      "identifier": {program_id},
      "update_results": {
        "program_modified": {
          "budget": {
            "status": "COMPLETED",
            "requested_value": {budget_value}
          },
          "program_id": {
            "status": "COMPLETED",
            "requested_value":{program_id}
          },
          "max_bid": {
            "status": "COMPLETED",
            "requested_value": {max_bid_value}
          }
        }
      }
    }
  ]
}
**Usage Example for changing end date:** **Example Request:** ```javascript curl \ --user "{username}:{password}" \ -X POST \ https://partner-api.yelp.com/v1/reseller/program/c6HT44PKCaXqzN_BdgKPCw/edit?end= ``` **Example Response:** ```javascript Response: { "job_id": "prvtN-nilb4mUynGGgKuBQ" } ``` ## Terminate Program ### HTTP POST **Request:** ```javascript curl \ -X POST \ --user "{username}:{password}" \ https://partner-api.yelp.com/v1/reseller/program//end ``` **Description:** This will immediately end the program specified by ``. [block:html] { "html": "\n
\n \n \n \n \n \n \n \n \n \n \n \n \n
Property NameValueOptionalDescription
program_idstringNoThe program_id to terminate
" } [/block] **Usage:** **Example Request:** ```javascript curl \ -X POST \ --user "{username}:{password}" \ https://partner-api.yelp.com/v1/reseller/program/c6HT44PKCaXqzN_BdgKPCw/end ``` **Example Response:** ```javascript Response: { "job_id": "prvtN-nilb4mUynGGgKuBQ" } ``` See sample request & response when viewing status of a job id for a terminated program: **Example Request:** ```javascript curl \ -X GET \ -H "Accept: application/json" \ --user "{username}:{password}" \ https://partner-api.yelp.com/v1/reseller/status/prvtN-nilb4mUynGGgKuBQ ``` **Example Response:** 
{

  "status": "COMPLETED",
  "completed_at": ,
  "created_at": ,
  "business_results": [
    {
      "status": "COMPLETED",
      "identifier_type": "PROGRAM",
      "identifier": ,
      "update_results": {
        "program_ended": {
          "status": "COMPLETED",
          "requested_value": 
        }
      }
    }
  ]
}
## Receipting ### HTTP GET **Request:** ```javascript curl \ -X GET \ --user "{username}:{password}" \ https://partner-api.yelp.com/v1/reseller/status/ ``` **Description:** This endpoint expects a job\_id, and will return the status of the updates associated with the job. **Usage:** **Example Request:** ```javascript curl \ -X GET \ -H "Accept: application/json" \ --user "{username}:{password}" \ https://partner-api.yelp.com/v1/reseller/status/c6HT44PKCaXqzN_BdgKPCw ``` Response: \ Example for CPC program\ 
{
  "status": [COMPLETED|PROCESSING],
  "completed_at": {datetime},
  "created_at": {datetime},
  "business_results": [
    {
      "status": [COMPLETED|PROCESSING],
      "identifier_type": "BUSINESS",
      "identifier": {yelp_business_id},
      "update_results": {
        "program_added": {
          "start": {
            "status": [COMPLETED|PROCESSING],
            "requested_value": {datetime},
          },
          "program_name": {
            "status": [COMPLETED|PROCESSING],
            "requested_value": {program_name}
          },
          "end": {
            "status": [COMPLETED|PROCESSING],
            "requested_value": {datetime},
          },
          "program_id": {
            "status": [COMPLETED|PROCESSING],
            "requested_value": {program_id}
          },
          "yelp_business_id": {
            "status": [COMPLETED|PROCESSING],
            "requested_value": {yelp_business_id}
          },
						"is_autobid": {
            "status": [COMPLETED|PROCESSING],
            "requested_value": [true|false]
          },
						"max_bid": {
            "status": [COMPLETED|PROCESSING],
            "requested_value": {max_bid_value}
          },
						 "budget": {
            "status": [COMPLETED|PROCESSING],
            "requested_value": {budget_value}
          }
        }
      }
    }
  ]
}
\ Example for BP program
{
  "status": [COMPLETED|PROCESSING],
  "completed_at": {datetime},
  "created_at": {datetime},
  "business_results": [
    {
      "status": [COMPLETED|PROCESSING],
      "identifier_type": "BUSINESS",
      "identifier": {yelp_business_id},
      "update_results": {
        "program_added": {
          "start": {
            "status": [COMPLETED|PROCESSING],
            "requested_value": {datetime},
          },
          "program_name": {
            "status": [COMPLETED|PROCESSING],
            "requested_value": {program_name}
          },
          "end": {
            "status": [COMPLETED|PROCESSING],
            "requested_value": {datetime},
          },
          "program_id": {
            "status": [COMPLETED|PROCESSING],
            "requested_value": {program_id}
          },
          "yelp_business_id": {
            "status": [COMPLETED|PROCESSING],
            "requested_value": {yelp_business_id}
          }
        }
      }
    }
  ]
}
## Pause Program ### HTTP POST **Request:** ``` javascript curl \ -X POST \ --user "{username}:{password}" \ https://partner-api.yelp.com/program//pause/v1 ``` **Response:** `HTTP 202` Empty response **Description:** This endpoint will allow a currently running CPC program to be paused. The campaign will temporarily stop running until it is resumed by the [Program Resume](#program-resume) endpoint. ## Resume Program ### HTTP POST **Request:** ```javascript curl \ -X POST \ --user "{username}:{password}" \ https://partner-api.yelp.com/program//resume/v1 ``` **Response:** `HTTP 202` Empty response **Description:** This endpoint will allow a currently paused CPC program to be resumed. # Advertising API Errors ## Error Codes The following general error codes may be returned by the Advertising API: [block:html] { "html": "\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
Error codeMessageDescription
503Service UnavailableThe API is currently unavailable\n
403Authorization ErrorSent when the partner is not authorized for a particular request (e.g. They don’t have access to either the business, metric, or time range requested.)
500Internal ErrorSomething went wrong.
202Job not completeThe job has been submitted and is being worked on. Please resubmit at another time.
400Invalid RequestThe request submitted is invalid
401Authentication ErrorThe user is not who they seem or their credentials are incorrect.
404Not FoundResource not found
\n" } [/block] ## Error Messages When the Advertising API returns a job\_id, the response from the /reseller/status/ endpoint may contain errors. The business\_results.status field can be set to REJECTED if the business is closed or removed from search or if the program is no longer active. The possible error codes may be returned in the business\_results.error.code field: [block:html] { "html": "\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
Error codeMessage
BUSINESS_NOT_ACTIVEThis business cannot be accessed because it is closed.
PROGRAM_NOT_ACTIVE_CLOSED_BUSINESSThis program is no longer active because has been closed. Contact partner-support@yelp.com if the business is erroneously closed.
PROGRAM_NOT_ACTIVE_BUSINESS_REMOVED_FROM_SEARCHThis program is no longer active because the business has been removed from search by Yelp due to duplicate, eligibility status, etc. Contact partner-support@yelp.com if the business is erroneously removed.
PROGRAM_HAS_EXPIREDThis program cannot be modified. The program is no longer active because the program end date has passed, or the business has been removed from search by Yelp due to being a duplicate listing, eligibility status, etc. Contact partner-support@yelp.com with the yelp_business_id if the business was erroneously ended or removed.
" } [/block] Here is an example error response: 
{
  "status": "COMPLETED",
  "completed_at": {datetime},
  "created_at": "{datetime},
  "business_results": [
    {
      "status": "REJECTED",
      "identifier_type": "BUSINESS",
      "identifier": {yelp_business_id},
      "error": {
        "message": "This program is no longer active because the business has been removed from search by Yelp due to duplicate, eligibility status, etc. Contact partner-support@yelp.com if the business is erroneously removed.",
        "code": "PROGRAM_NOT_ACTIVE_BUSINESS_REMOVED_FROM_SEARCH"
      }
    }
  ]
}
Even if the business\_results.status field is set to COMPLETED, there may be errors in when the update\_results.program\_added.status or update\_results.program\_modified.status is set to REJECTED. The possible error codes may be returned in the update\_results.program\_added.error.code or update\_results.program\_modified.error.code field in this scenario: [block:html] { "html": "\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
Error codeMessage
INVALID_OR_MISSING_KEYInvalid or missing required key(s): {required_keys}
PROGRAM_ALREADY_RUNNING_BY_ANOTHER_PROVIDERYou cannot run this program because the client has already purchased this product from another provider.
CANNOT_ADD_PROGRAM_IN_PASTCannot add a program that starts in the past.
PROGRAM_ALREADY_REQUESTEDYou already requested to enable this product for this client.
CONFLICTS_WITH_ANOTHER_ACTIVE_PROGRAMThis program conflicts with a currently active or recently ended program. If you are trying to add a new program, please use a start date subsequent to the end date of any conflicting programs.
PARENT_WAS_REJECTEDAnother part of your request failed, check the other attributes of our response to find the root error cause.
CANNOT_DECREASE_BUDGET_BELOW_AMOUNT_ALREADY_SPENTCampaign has already spent {amount_spent}. Cannot decrease budget below actual spend.
CURRENCY_MISMATCHCannot change current type; currency must remain consistent.
BUSINESS_RESTRICTED_FROM_ADVERTISINGYelp has blocked this locations ability to purchase advertising. Reach out to partner-support@yelp.com to request an exception to this block.
INVALID_PRICEInvalid price. Must be numerical formatted in cents.
UNSUPPORTED_CATEGORIESCategory is not supported: The category of the business you are trying to advertise is declined due to policy restrictions.
BID_TOO_HIGH_FOR_BUDGETBid exceeds total prorated budget. Please increase budget to increase your chances of ad display.
COULD_NOT_MODIFY_PROGRAMCould not modify specified program.
NO_CATEGORIESThe business does not have categories or they are awaiting approval.
CAMPAIGN_BUDGET_VIOLATES_PROMO_RESTRICTIONSCampaign budgeted outside of restrictions set by associated promo.
" } [/block] Here is an example error response: 
{
  "status": "COMPLETED",
  "completed_at": {datetime},
  "created_at": "{datetime},
  "business_results": [
    {
      "status": "COMPLETED",
      "identifier_type": "BUSINESS",
      "identifier": {yelp_business_id},
      "update_results": {
        "program_added": {
          "status": "REJECTED",
          "requested_value": {
          ...

 




```
```

> πŸ“˜ Check out our Advertising API Reference Page
> 
> :owlbert: [Advertising API Endpoints](https://docs.developer.yelp.com/v1.0/reference#create-profile)