Data Ingestion API - Frequently Asked Questions

Table of Contents

• Getting Started and Authentication
• Matching and Identifying Businesses
• Submitting Updates
• Data Quality and Moderation
• Subscriptions and Billing
• Rate Limits
• Closures, Reopenings, and Listing Lifecycle
• OAuth and Token Management
• Private Reviews API
• Respond-to-Review API
• Testing and Development
• Related APIs (Fusion / Business Match)

---

Getting Started and Authentication

How are Data Ingestion API credentials scoped?

Credentials are scoped per partner. You receive a single set of credentials that you use to manage all business listings under your account. You do not need separate credentials per customer or per business.

Can we create multiple accounts (dev, staging, prod) with separate credentials?

No. You have one set of credentials for your integration.

Do we need business owner authorization to push listing updates?

No. You can push listing updates without any business owner authorization. However, responding to reviews requires the business owner to complete an OAuth flow. See the Authorization Code Workflow for details.

What triggers a BUSINESS_AUTHORIZATION_FAILED error?

This error means you attempted to update a business outside the countries specified in your contract.

When we onboard a new customer, does Yelp need to do anything on their side?

No additional Yelp setup is required per customer. Follow the subscription flows in the Listings Management Guide and you're all set.

If a customer adopts our platform as their source of truth, should they stop managing Yelp directly?

Yes. Once they onboard your platform to manage their Yelp listing info, they should not also log in to biz.yelp.com to post the same updates. Managing in both places can lead to conflicts and unintended overwrites.

How should we handle OAuth token revocation if a customer churns?

As a best practice, revoke their token when a customer disables or cancels their connection to your platform. This should be an automated backend process triggered by their cancellation action.

Are redirect URLs or tracking URLs allowed for the website URL field?

No. Yelp requires the actual business website URL, not a tracking or redirection service that forwards traffic to a different URL.

How do we get test business IDs for development?

Yelp provides test business IDs during your onboarding process. These are permanent and available for the duration of your partnership. If you need additional test IDs for automated testing pipelines, contact [email protected].

What countries are partners allowed to update via the Data Ingestion API?

Partners can update listings in the US, Canada, and US territories (PR, GU, VI) as specified in their contract.

---

Matching and Identifying Businesses

How does matching work when we submit an update?

When you include matching_criteria in your request, Yelp uses those fields to identify the correct business listing. If you know the yelp_business_id, you should also provide the current name and address in matching criteria (fetched from the business details endpoint) to confirm the match.

If we provide both yelp_business_id and name/address, and they point to different businesses, what happens?

You will receive an error. If you know the business ID you want to update, use the Business Details endpoint to fetch that business's current name and address, then use those values in matching criteria.

Does sending partner_id improve matching accuracy?

No. The partner_business_id simply stores a mapping between your internal ID and Yelp's ID. It is not displayed to users and does not influence matching logic.

What does use_matching_criteria_for_update do?

When set to false, the matching criteria is only used for identifying the listing, not applied as an update. We recommend always setting this to false, then explicitly specifying the attributes you want to change in the update section.

Can a business listing exist without a yelp_business_id changing over time?

Business IDs can change if Yelp merges duplicate listings. When this happens, you can detect merges using the Business Migration Info API. We recommend pointing to the new (winning) ID once you notice a merge.

What happens if we keep sending updates to an old (merged) business ID?

Once a page is merged, Yelp forwards requests to the winning ID. However, we recommend updating your records to point directly to the winning ID after you detect the merge.

How does Yelp handle locations with the same address but different business names and contact numbers?

Each location is evaluated individually. If the businesses are genuinely separate entities operating at the same address, they can each have their own listing. If they appear to be duplicates, they may be flagged for review. Contact [email protected] if you need duplicates merged.

What is the process to merge duplicate locations?

Contact [email protected] with the business IDs you believe are duplicates. Yelp's team will evaluate and merge if appropriate.

If we create new locations, how long do these take to be reviewed?

New location creation is typically reviewed within approximately 48 hours.

Is the job_id unique to each request?

Yes. Each API request gets its own unique job_id. Subsequent updates to the same listing generate new job IDs.

---

Submitting Updates

Should we send only changed fields or the complete object every time?

Send only the fields that have changed. If a field hasn't changed, do not include it in the update object. Yelp only modifies what you submit. If you omit a field entirely, the existing value on the listing is preserved (it will not be deleted).

Do not resend unchanged data. Even if the data is still accurate, redundant submissions should be avoided.

Will omitting fields from an update cause existing data to be deleted?

No. If you omit a field from the update object, the current value remains unchanged on the listing. Only fields explicitly included in the update are modified.

Is the recommended approach to fetch current data before every update?

Yes. Calling GET /v1/business_info/{yelp_business_id} before updates is a good approach to ensure you only send desired changes. This endpoint returns the current data on the listing.

What are the mandatory fields for an update?

The update object has no mandatory fields, but it cannot be empty. You must include at least one field you want to change. However, matching_criteria always requires name and address.

What is the difference between url and display_url?

url is where the traffic routes when a user clicks. display_url is what Yelp shows visually on the listing page.

Can we update categories for a listing?

You can add categories to a listing that currently has no categories assigned. However, changing existing categories on a listing that already has them requires coordination with your Yelp contact, as category changes are restricted to prevent misuse (Yelp search relies heavily on business categories).

Where can we find Yelp's category list?

The complete list of valid category aliases is available in the Yelp API documentation.

What fields can we update via the API?

The updatable fields fall into these categories:

• Business identity: name, categories, opening date
• Location: address1, address2, city, state, postal_code, country, latitude, longitude, service_area
• Contact: phone, url, menu_url
• Hours: hours (including split hours across days)
• Status: closed, temporarily_closed
• About the business: about_this_business_history, about_this_business_specialties, about_this_business_year_established, about_this_business_bio, about_this_business_bio_first_name, about_this_business_bio_last_name
• Amenities/attributes: take_out, delivery, dogs_allowed, alcohol, caters, happy_hour, has_tv, outdoor_seating, parking, takes_reservations, wheelchair_accessible, wifi, by_appointment_only, coat_check, smoking, waiter_service, accepts_credit_cards, accepts_insurance
• Media: photos

Not all fields will be relevant to every partner's use case. See the full reference at the Data Ingestion API docs.

Can we trigger a new update while a previous one is still processing?

Yes. You can send additional updates at any time. The most recent update replaces the older one for the same attributes.

What happens if we send duplicate updates for the same attribute while one is in the queue?

The most recent update wins. You may see an attribute_already_in_queue status on the earlier update, meaning a newer submission replaced it. If you have a correct value, send it regardless of pending updates.

Does resending unchanged fields trigger a new moderation review?

Yelp should ignore or fast-track unchanged data, but you should still avoid submitting redundant updates. Only send data that has actually changed.

How should we submit UTM parameters?

Do not include UTM parameters. Submit only organic page URLs.

What are the guidelines for the "About Business Specialties" field?

This field is moderated. Avoid keyword stuffing and provide genuine, descriptive content about the business's specialties.

Does Yelp support split hours for business hours spread across two days?

Yes. For example, if a business is open 4pm to 2am, you can represent this with hours spanning across midnight.

Can we send menu data?

Contact [email protected] to discuss menu data requirements and available options.

Are there any permanent banners on a profile accessible via the API?

Two free-text banner fields are available for certain business types. Check your contracted field list for availability.

Can we update the partner_business_id after it's been set?

Yes. You can update the partner_business_id value.

If a listing has no categories and we submit an update without a categories field, will the update fail?

No. The update will proceed normally for the other fields you include. The categories field is only required if you are specifically trying to set categories.

When polling job status, what does COMPLETED at the job level mean?

COMPLETED means there are no pending attribute updates remaining in that request. However, you should still check each individual attribute's status rather than relying solely on the top-level job status. Individual attributes will show COMPLETED, APPLIED, REJECTED, or FAILED.

How long is job feedback available for polling?

Job feedback is available for 14 days from the time the request was submitted (not from when it finishes processing). Poll regularly to capture status updates.

Is there a guaranteed processing time for updates?

No. There is no guaranteed timeframe for processing. Moderation queues can fluctuate based on volume and team bandwidth. For non-creation updates, polling daily is recommended.

What does the comment attribute map to?

Check the Data Ingestion API docs for the complete list of attribute names and their descriptions. Field names are intuitively named to match what appears on the consumer-facing page.

Is there a reference showing where each attribute appears on the consumer UI?

Field names correspond to what you see on a business's public Yelp page. Visit yelp.com and browse business pages to see where each attribute appears.

Can multiple partners submit conflicting data for the same business?

Multiple partners can update the same listing. Yelp does not block updates based on other partners. The most recent update to any given field is what gets displayed. Simply send the correct, current data. We ask that you only send recently updated data (do not re-submit stale data that was previously sent months ago).

---

Data Quality and Moderation

How long do updates take to be published on Yelp?

Processing time depends on your data quality tier:

• Auto-approve: Updates are published immediately without moderation review.
• Publish-then-review: Updates go live right away but may be reviewed and rolled back if issues are found.
• Review-then-publish: Updates are held in moderation queue until reviewed before going live.

Moderation review times vary based on queue volume. There is no fixed SLA.

What data quality tier do new partners start at?

Your starting tier is determined by an initial data quality study. Partners submit a sample dataset for Yelp's moderation team to review. Following the Data Quality Guidelines and pre-normalizing your data before the initial study can help you start at a higher tier.

How are data quality tiers reviewed and changed?

Yelp reviews partner data quality quarterly. Tiers are applied per attribute (not globally across all fields). Changes to your tier can happen at each quarterly review based on data from the most recent quarter only.

Can sending non-normalized data affect our permission tier?

Yes. All updates go through the moderation queue. Partners are expected to follow Yelp's normalization guidelines. Submitting data that doesn't follow normalization rules (including phone number formatting, address abbreviations, and name prefixes) could negatively impact your permissions.

How should we format phone numbers?

Per the Data Quality Guidelines and API docs: submit phone numbers either locally-formatted with digits only (e.g., 6175551234) or internationally-formatted with a leading + and digits only (e.g., +16175551234). Maximum length is 32 characters.

Will drastically changing an address or name cause issues?

Updates should be accurate and match the Data Quality Guidelines. Moving a previously validated listing to a distant location (different state or non-adjacent city) would be flagged as unusual and may trigger additional moderation scrutiny.

If a customer stops advertising, what happens to their data?

Listing data managed through the Data Ingestion API remains on the listing regardless of advertising status. Advertising products (Enhanced Profiles, CTAs) are separate from listing management.

---

Subscriptions and Billing

How do we enable a location for Yelp listing updates?

Subscribe to the business's yelp_business_id using the subscription API. See the Listings Management Guide for the full workflow.

How do we disable a location for Yelp listing updates?

Unsubscribe from the business's yelp_business_id. You should unsubscribe immediately when a customer is offboarded, since subscription status directly informs billing. Subscribed businesses are subject to billing.

How should we use the location subscription and listing management subscription APIs?

Follow the subscription flows documented in the Listings Management Guide.

Can multiple partners subscribe to the same business ID?

Yes. You do not need to consider or account for other partners' subscriptions in your integration.

What happens to a subscription when a business ID is merged?

Subscriptions should transfer to the new (winning) business ID automatically.

If a page is removed from search by Yelp moderators, is our subscription automatically cancelled?

No. You should still manually unsubscribe from that listing.

How long does subscription processing take?

Status updates typically arrive within 15 minutes. However, if you are subscribing or unsubscribing to many IDs at once, full processing can take up to 60 minutes.

Are there scenarios where Yelp would drop our subscriptions?

No. Yelp does not unilaterally drop partner subscriptions.

Is there a yearly removal limit for subscriptions?

The limit is set high enough that you will not hit it under normal usage. You do not need to factor this into your integration.

How do we identify Mutually Enterprise Customers (MECs)?

MEC status is accessible via an API response attribute for contracted partners. These are customers who have purchased advertising through their Yelp representative.

Does a customer need MEC status for us to manage their listings?

Yes. The customer needs to purchase advertising via their Yelp rep to attain MEC status, which enables your partner API access to manage their listings.

---

Rate Limits

What are the rate limits for the Data Ingestion API?

The default rate limit is 2,500 requests per 30 minutes, enforced per endpoint. This means you get:

• 2,500 requests for POST /v1/ingest/create
• A separate 2,500 requests for GET /v1/ingest/status/{job_id}

These are independent pools, not shared across endpoints.

Is the 30-minute window sliding or fixed?

Fixed window.

Can the rate limit be increased?

The 2,500/30min limit should be sufficient for most integrations. You can batch multiple business IDs into a single request to optimize throughput. If you have a specific need, contact [email protected].

Is there an SDK or OpenAPI specification available?

No. There is no official SDK or OpenAPI spec at this time.

---

Closures, Reopenings, and Listing Lifecycle

Does Yelp support "Temporarily Closed"?

Yes. Use the temporarily_closed field. You can include specific dates or leave it open-ended to indicate an unknown reopening date.

How should we format data for a location that is temporarily closed with no known reopening date?

Set temporarily_closed without a specific end date. This signals that the business is temporarily closed but the reopening date is unknown.

What happens if we send an update to a permanently closed listing (is_closed = true)?

The request will fail with a BUSINESS_NOT_ACTIVE error. You cannot update closed listings through the API.

Can we update unclaimed listings?

Yes. Claimed status does not affect your ability to push updates via the API.

Does Yelp have a concept of grouping listings under a parent organization or brand?

Not externally through the API. Organization-level grouping is handled through the claiming flow, where a business owner is added to multiple pages, linking them as a single account on Yelp's side.

What about field locking when a business owner edits their listing?

If a business owner updates a field directly on biz.yelp.com, that field may be temporarily locked from partner API updates for approximately 30 days. This is an automated process designed to respect the business owner's most recent intent. The best practice is to advise your customers not to make direct edits on biz.yelp.com if they are using your platform for listing management.

Does subscribing to a listing clear any existing field locks?

No. Subscribing is unrelated to field locking. If a business owner was previously editing fields on biz.yelp.com, those locks persist regardless of your subscription status.

Can we delete photos on Yelp?

Only photos that were added by your partner account can be removed. User-uploaded photos cannot be deleted through the API.

Do we have the ability to add or update call-to-action buttons?

No. Call-to-action buttons are part of Yelp's Enhanced Profile advertising product. They are managed by the party purchasing the advertising, not through the Data Ingestion API.

Does Yelp have a posts section on profiles?

Posts are a paid advertising feature managed through Yelp's advertising products, not available through the Data Ingestion API.

Can we detect if a business has an Enhanced Profile (paid advertising) via the API?

No. Enhanced Profile status is not exposed through the API. CTA buttons and other advertising features are managed exclusively by the advertising purchaser.

Does Yelp offer a bulk data export for existing listing data?

No. There is no "download all your data" UI or bulk export tool. You have contracted access to the API; use the business details endpoint to programmatically retrieve current listing data as needed.

---

OAuth and Token Management

Should we use /oauth2/token (v2) or /oauth2/token/v3 for refreshing tokens?

Either works. The difference: v3 returns a new refresh token on each call, which resets the 365-day expiry and reduces the chance of needing the business owner to re-authorize. If you use v3, make sure you capture and store the new refresh token returned with each call.

Do access tokens expire? What happens when they do?

Yes. The response that includes the access_token and refresh_token also includes expiry dates for both. If the refresh token expires before you use it to get a new access token, the business owner will need to complete the OAuth flow again.

Is claiming required for enterprise customers to use Respond-to-Review?

Yes. A business owner needs to be claimed on a Yelp page to respond to reviews. For enterprise businesses, claiming is handled through a coordination process with your Yelp contact. SMBs claim directly on Yelp via https://biz.yelp.com/signup/<biz_id>/account.

---

Private Reviews API

When Yelp merges two listings, do reviews from the source listing carry over?

Yes. Reviews from the merged (source) listing transfer to the surviving listing.

Does the Private Reviews feed return reviews for permanently closed listings?

Yes. You can still retrieve reviews for closed listings via the Private Reviews API.

When a reviewer updates their review, does the API return both old and new versions?

No. The Private Reviews API returns only the most recent version of a review.

Can a business owner suppress or hide reviews from the API feed?

No. You control review retrieval through your subscription to a business ID. As long as you're subscribed, reviews are accessible.

---

Respond-to-Review API

Can a business owner edit or delete a review response via the API?

You cannot delete a response via the API. To overwrite an existing reply, POST a new response to the same review. The new reply replaces the previous one. To delete a reply entirely, the business owner must do so through biz.yelp.com.

Can we pass an empty string to effectively delete a reply?

No. The API rejects empty response text. Deletion must be done through biz.yelp.com.

What happens if a different business user tries to respond to a review that already has a reply?

Only the user who originally posted the reply can overwrite it. If a different business user on the same account attempts to respond to a review that already has a reply from another user, they will receive an error: "Review already has a comment by a different business user." Check the user ID of the existing reply against the OAuth user's ID to confirm they match before attempting an overwrite.

Can we redirect the business owner to a specific review on Yelp?

Direct the user to https://biz.yelp.com/r2r/{biz_id} where they can navigate to the specific review. Do not construct URLs pointing directly to individual review IDs.

---

Testing and Development

Can we get a test environment with instant updates (no moderation)?

No. All requests from your account are treated the same. Yelp cannot auto-approve updates for some businesses while moderating others. Updates to test listings go through the same moderation process as production listings.

What statuses should we expect after submitting a test update?

After initial processing (assuming no failure), your update will be in one of these states:

• PROCESSING - awaiting moderator review
• APPLIED - posted live while waiting for moderator review
• COMPLETED - posted live, not subject to further moderator review

Build your integration to programmatically handle all possible statuses documented in the API results section.

If we resubmit an update that was previously rejected, what happens?

Yelp will auto-reject it. You should not resubmit the same data that was previously rejected without making corrections first.

---

Related APIs (Fusion / Business Match)

What is the rate limit for the Fusion API (api.yelp.com/v3/*)?

All endpoints under https://api.yelp.com/v3/* share a daily rate limit. Partners are typically granted 50,000 requests/day. If you need more, email [email protected] with your requested volume.

You can check your current daily limit and QPS at https://www.yelp.com/developers/v3/manage_app.

Should we fetch business details before every update?

Yes, this is the recommended pattern. Call the business details endpoint to get the current state of the listing, then only include fields in your update payload that you actually want to change. This prevents accidentally deleting data by sending null or empty values.

What are the mandatory inputs for the Business Info endpoint?

The yelp_business_id is the only required input.

Does the matching_criteria need to reflect the currently published data, or does it account for pending updates?

Yelp's matching looks at the live/published data on the listing, not pending updates in the moderation queue. If you fetch the current details via the business info endpoint and use those values in matching_criteria, that will work correctly even if you have pending updates.

---

Common Error Codes

For other error codes (EMAIL_IN_USE_ERROR, INVALID_JOB_ATTRIBUTE_RELATIONSHIP, INCOMPATIBLE_JOB_ATTRIBUTE_VALUES, ATTRIBUTES_CONFLICT), contact [email protected] with the full error response if you cannot resolve the issue from context.

---

For additional questions or edge cases not covered here, contact [email protected].