📘

This is a Yelp Partner API

Access is disabled by default. See Yelp Partner APIs on how to get access.

Overview

This document provides a reference to all API endpoints and sample responses available to manage Yelp advertising campaigns.

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 https://partner-api.yelp.com/v1/.

Format

Response bodies use the application/json content type and should be encoded in UTF-8.

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, WavvLdfdP6g8aZTtbBQHTw, but no other photo or business will have that same identifier.

Value Types

All date properties should use the YYYY-MM-DD format.

Yelp Business IDs

The Advertising API requires encrypted business IDs to create new programs. Please reference our Business Match API documentation 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:

Create Program

HTTP POST

https://partner-api.yelp.com/v1/reseller/program/create

Request:

curl \
  -X POST \
  --user "{username}:{password}" \
  https://partner-api.yelp.com/v1/reseller/program/create?start=<date>&end=<date>&business_id=<yelp_business_id>&program_name=<program_name> 

Description:

This endpoint will create the program <program_name> to the Yelp business as specified by <business_id>. 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. <business_id> and <program_name> are the required parameters for all program types. For CPC programs, <budget> and <is_autobid> is required. The <max_bid> parameter is also required for CPC programs if <is_autobid> 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.

CPC Program Parameters: (create)

The following table describes the request parameters for CPC programs.

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:

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:

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:

curl \
  --user "{username}:{password}" \
  -X POST \
  https://partner-api.yelp.com/v1/reseller/program/create?business_id=WavvLdfdP6g8aZTtbBQHTw&program_name=BP

Example Response:

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:

curl \
  --user "{username}:{password}" \
  -X POST \
  https://partner-api.yelp.com/v1/reseller/program/create?business_id=WavvLdfdP6g8aZTtbBQHTw&program_name=EP

Example Response:

Response: 
{
	"job_id": "prvtN-nilb4mUynGGgKuBQ"
}

See Receipting for responses after completion of the request

Modify Program

HTTP POST

https://partner-api.yelp.com/v1/reseller/program/{program_id}/edit

Request:

curl \
  -X POST \
  --user "{username}:{password}" \
  https://partner-api.yelp.com/v1/reseller/program/<program_id>/edit?start=<date>&end=<date>

Description:

This endpoint will allow modification to attributes of an existing program, <program_id>. 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.

CPC Program Parameters: (edit)

The following table describes the request parameters for CPC programs.

Usage Example for modifying budget to $250.00 and maximum bid to $10.00:

Example Request:

curl \
  --user "{username}:{password}" \
  -X POST \
  https://partner-api.yelp.com/v1/reseller/program/c6HT44PKCaXqzN_BdgKPCw/edit?budget=25000&max_bid=1000

Example Response:

Response: 
{
	"job_id": "yf8sGfL9NNRpHoXmKudBwg"
}

See sample request & response when viewing status of a job id for a modified program:

Example Request:

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:

curl \
  --user "{username}:{password}" \
  -X POST \
  https://partner-api.yelp.com/v1/reseller/program/c6HT44PKCaXqzN_BdgKPCw/edit?end=<date>

Example Response:

Response: 
{
	"job_id": "prvtN-nilb4mUynGGgKuBQ"
}

Terminate Program

HTTP POST

https://partner-api.yelp.com/v1/reseller/program/{program_id}/end

Request:

curl \
  -X POST \
  --user "{username}:{password}" \
  https://partner-api.yelp.com/v1/reseller/program/<program_id>/end

Description:

This will immediately end the program specified by <program_id>.

Usage:

Example Request:

curl \
  -X POST \
  --user "{username}:{password}" \
  https://partner-api.yelp.com/v1/reseller/program/c6HT44PKCaXqzN_BdgKPCw/end

Example Response:

Response: 
{
	"job_id": "prvtN-nilb4mUynGGgKuBQ"
}

See sample request & response when viewing status of a job id for a terminated program:

Example Request:

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

https://partner-api.yelp.com/v1/reseller/status/{job_id}

Request:

curl \
  -X GET \
  --user "{username}:{password}" \
  https://partner-api.yelp.com/v1/reseller/status/<job_id>

Description:

This endpoint expects a job_id, and will return the status of the updates associated with the job.

Usage:

Example Request:

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

https://partner-api.yelp.com/program/{program_id}/pause/v1

Request:

javascript
curl \
  -X POST \
  --user "{username}:{password}" \
  https://partner-api.yelp.com/program/<program_id>/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 endpoint.

📘

This feature is coming soon

Please get in touch if you would like to get early access

Resume Program

HTTP POST

https://partner-api.yelp.com/program/{program_id}/resume/v1

Request:

curl \
  -X POST \
  --user "{username}:{password}" \
  https://partner-api.yelp.com/program/<program_id>/resume/v1

Response:

HTTP 202 Empty response

Description:

This endpoint will allow a currently paused CPC program to be resumed.

📘

This feature is coming soon

Please get in touch if you would like to get early access

Advertising API Errors

Error Codes

The following general error codes may be returned by the Advertising API:

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:

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 [email protected] 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:

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": {
          ...
            
          "error": {
            "message": "You cannot run this program because the client has already purchased this product from another provider.",
            "code": "PROGRAM_ALREADY_RUNNING_BY_ANOTHER_PROVIDER"
          }
        }
      }
    }
  ]
}

📘

Check out our Advertising API Reference Page

Advertising API Endpoints