Getting Started with the Ads API

This page walks you through what to expect when onboarding to the Yelp Ads API, from receiving test credentials to going live.

Table of Contents

• Overview
• Step 1: Receive Test Credentials
• Step 2: Test Your Integration
• Step 3: Go Live
• Getting Help

---

Overview

The Ads API onboarding process follows two phases:

1. Test phase — you receive test credentials scoped to a set of pre-configured test business listings. Use these to build and validate your integration without affecting real campaigns.
2. Live phase — once your integration is validated, you receive live credentials tied to your active payment account and can begin managing real campaigns.

---

Step 1: Receive Test Credentials

Test credentials are issued by Yelp's Solutions Engineering team after your access request has been processed.

Test credentials include:

• A username and password for authenticating against https://partner-api.yelp.com/v1/
• A set of test business IDs — these are pre-configured Yelp listings set aside specifically for Ads API testing. Your SE will provide these IDs along with your credentials.

📘

Don't have a Solutions Engineer?

If you haven't been assigned a Yelp Solutions Engineer, reach out to your Yelp account representative to get connected with one before proceeding.

Test credentials are intentionally scoped to specific test listings and cannot be used to create programs on real business accounts. This is by design.

---

Step 2: Test Your Integration

Use your test credentials and the provided test business IDs to validate your integration end-to-end before going live. The goal is to confirm that your system can correctly handle the full program lifecycle.

Recommended test scenarios

Program creation

• Create a CPC program on a test business ID with a valid budget (minimum 2500 cents = $25.00) and is_autobid: true
• Confirm the response returns a job_id
• Poll GET /v1/reseller/status/{job_id} until the status reaches COMPLETED or REJECTED
• Confirm the program_id is returned in the response

Program modification

• Modify the budget on the program you created
• Confirm the job completes successfully via the status endpoint

Program termination

• Terminate the test program
• Confirm the job completes and the program status reflects the change

Error handling

• Submit a request with a missing required field and confirm your integration correctly handles a REJECTED job response
• Confirm your integration can parse PARENT_WAS_REJECTED cascading errors and identify the root cause field

Job polling logic

• Confirm your system does not assume success from the initial 200 response alone
• Confirm your system polls until a terminal state (COMPLETED or REJECTED) before taking downstream action

📘

Before you build

Review Campaign Management Behavior & Nuances and Async Job Processing & Error Handling before writing your integration. These pages cover the non-obvious behaviors — async validation, feature carryover, SCT limitations — that are the most common sources of integration issues.

When you're ready to go live

Once you've validated the scenarios above and are confident in your integration, notify your Yelp Solutions Engineer that you're ready for live credentials. They will coordinate next steps.

---

Step 3: Go Live

Live credentials are issued after your test integration is validated. Unlike test credentials, live credentials are tied to your active Yelp payment account and will create real programs on real business listings.

What changes when you go live:

• Your credentials are scoped to your payment account — programs created will be billed against it
• You will use real business IDs (encrypted Yelp business IDs) from the businesses you manage
• All programs created are live and will begin serving ads per their start date

⚠️

Important

Live credentials are issued directly to the authorized technical contact at your organization. Credentials should not be shared with third-party platforms or sub-contractors without first consulting your Yelp Solutions Engineer.

---

Getting Help