> ## Documentation Index
> Fetch the complete documentation index at: https://docs.birdeye.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get
> Get Reviews returns reviews for a business account with detailed review fields.
> __Behavior Note__
> - _If `statuses` is not provided, the API defaults to `["published"]`, which returns featured reviews only._
> - _Status mapping: `published` = featured reviews, `parked` = non-featured reviews._
> - _To fetch both featured and non-featured reviews, pass `statuses: ["published","parked"]` or `statuses: ["all"]` in the request body._
> - _`ratings` filters are applied only within the statuses selected for the request._
> __Note__
> - _Deep Pagination with record window greater than 100k is not supported. Either reduce the sindex + count to be less than equal to 100k or use appropriate filters to narrow down your result set._
## OpenAPI
````yaml api/openapi.yaml POST /v1/review/businessId/{businessId}
openapi: 3.0.0
info:
title: Birdeye
version: 0.0.1
description: >-
Birdeye helps businesses grow through happy customers. Over 80,000
businesses use Birdeye everyday to attract new leads with Listings, Reviews
and Referrals, convert them into customers with Webchat, Appointments, and
Payments, and delight those customers with Surveys, Ticketing, and Insights
- all in one place.
The Birdeye APIs are built on HTTP and are RESTful APIs.
* Uses resource-oriented URLs.
* Uses built-in HTTP capabilities for passing parameters and authentication.
* Responds with standard HTTP response codes to indicate errors.
* Requests and responses payload attached with all the mentioned APIs, you
may choose your preferred language per the integration requirement.
### Authentication and Rate limiting
> __NOTE:__
> - __All API requests targeting business accounts must include the
x-api-key header. This header is required and mandatory for successful
authentication and access to the API endpoints.__
>
> - __To protect your API key and prevent unauthorized access, please ensure
all API requests are made from your backend server. Do not call the APIs
directly from the browser or expose your API key in any client-side code.__
To call a Birdeye API, you need a valid API key. It can be fetched via the
Birdeye dashboard and is a confidential key.
There is a limit to calling APIs with each API key [connect with the support
team to get the current limit]. If too many requests are made within the
threshold timeframe, an error will be returned in the response.
### Pagination
Multiple API supporting pagination. These APIs have two parameters sindex
and count.
* sindex: is the start index
* count: No. of records, you want to fetch.
> __Note__
> - _Deep Pagination with record window greater than 100k is not supported.
Either reduce the sindex + count to be less than equal to 100k or use
appropriate filters to narrow down your result set._
For example :
* Suppose you have to fetch 20 records:
API call 1 -> sindex=0, count 10
API call 2 -> sindex -> 10, count 10.
* To fetch 100kth record:
sindex = 99000 and count = 1000
will just work fine as sindex + count = 100000 which is less than 100,000.
* If you fetch more than 100kth records:
sindex = 99000 and count = 1001, sindex + count = 100001
which is greater than 100,000. Thus, you'll receive an error in response.
### HTTP Status Codes
Every API response will have an HTTP status code.
* 200 - OK: API request is successful
* 202 - Accepted: The API request has been accepted for processing.
* 400 - Bad Request: The API request was unacceptable, often due to a
missing or invalid parameter.
* 404 - Not Found: The requested resource does not exist.
* 429 - Rate Limited: You have made too many requests within the
threshold timeframe.
* 500 - Internal Server Error: Something went wrong on our end.
Please get in touch with support.
### Error Response
Birdeye API will return a validation error in case of missing/invalid input
in the request. The response will return the errorCode and errorMessage.
For example :
{
"code": 1161,
"message": "Invalid API key"
}
servers:
- url: https://api.birdeye.com/resources
security: []
tags:
- name: Business
description: Create and maintain your business on Birdeye.
- name: Custom Fields
description: Create, delete , update , associate and get custom fields easily.
- name: User
description: Delete and manage user profiles and permissions easily.
- name: Reviews
description: Consistently generate more reviews and higher ratings.
- name: Contact
description: >-
Manage contacts across locations effortlessly with a robust Contact
Management System.
- name: Contact V2
description: >-
Easily manage contacts across multiple locations using enhanced Contact
APIs, featuring built-in support for communication preference flags.
- name: Campaign
description: >-
Create a short link for review requests and set review sources in the
template.
- name: Aggregation
description: Access your public data from 150+ review sites.
- name: Report
description: >-
Various reporting data points across Birdeye modules like reviews,
insights and competitors etc for all your data visualisation
- name: Survey
description: >-
Engage each customer at the right time with NPS or CSAT surveys to improve
your service.
- name: Business Media
description: >-
Add, delete and manage business media.
> __Supported Media Size__
> - _Photo: JPG or PNG. 720 x 720px. 10KB min._
> - _Video: 30 sec long. 720p or more upto 75MB._
> __Note__
> - _Uploaded media will be pushed to your google business profile (if
connected) and other long tail directories only._
- name: Social
description: Create and track Social posting for all channels.
- name: Employee
- name: Conversation
description: >-
Connect with customers across a range of digital channels from one unified
inbox.
- name: Subscription
description: >-
Subscribe or Unsubscribe multiple webhooks with different URLs or Events
for a subscription and deliver real-time notifications.
- name: Webhook
description: >-
Configure multiple webhooks with different URLs for a subscription and
deliver real-time notifications.
- name: Competitor
description: Make competitive insights your unfair advantage.
- name: Competitor AI
description: Competitive intelligence, simplified by AI.
- name: Insight AI
description: Insight intelligence, simplified by AI.
- name: Google Q&A
description: >-
> __Note__
> - _Applicable to be used only by paid listings clients, for their active
locations, for the Google Q&A section, in the Google listing_
- name: Google Services
description: >-
> __Note__
> - _Applicable to be used only by paid listings clients, for their active
locations, for the Google Services section, in the Google listing._
> - _No two services should have the same service name. It is recommended
that all services created should HAVE UNIQUE service names._
> - _You CAN have the same service across two diff categories e.g.:
Emergency counselling as a $100 paid service can be a service created &
mapped to category A - Mental health and category B - Psychotherapy - both
categories being present for the same location._
- name: FAQ
description: >-
To retrieve all Question and Answer (QnA) entries across locations using
FAQ APIs, enabling smart support and knowledge features for businesses.
- name: Listing
description: >-
Keep your business information accurate and consistent across 50+
websites.
- name: GMB Products
description: >-
To manage products, locations, and business details through Listing GMB
platform
- name: Search AI
description: >-
Search AI provides a comprehensive view of your business performance
across AI-powered search platforms, including data accuracy, sentiment
analysis, citations, brand ranking, and overall visibility.
- name: Ticketing
description: >-
Create standout customer support with ticketing across reviews, untagged,
and survey responses.
- name: Integration
description: Birdeye integrates with various software or tools you use.
- name: Change Logs
description: >-
* 07/03/2026 - Updated `mainBusinessDescription` and microsite
`internalListing.description` fields in Create, Update and Get Listing
APIs to be optional instead of required, with support for clearing the
existing value by sending an empty string (V2BIRD-1690).
* 06/10/2026 - Updated Get Contact API to support an optional
`experienceScore` boolean field in the request body (default: false). When
set to true, the response includes the customer's experience score and
source.
* 05/25/2026 - Added Update Custom card (PUT) and Delete Custom
card (DELETE) API documentation under the Business profile custom card
section.
* 05/11/2026 - Added support for backdated survey responses in the
POST Survey Response API. The `created` field (UTC Epoch milliseconds) is
optional; if omitted, the server defaults to the current UTC timestamp.
* 04/22/2026 - Provide subLocality field support in Get, Create and
Update Listings APIs for NZ Locations.
* 04/16/2026 - Added Archived Get Reviews API under Reviews group.
* 04/06/2026 - Updated Get Reviews API documentation to improve
clarity on review statuses and how to retrieve all review types.
* 03/24/2026 - Added Social Open URL Performance Report API and
Insight AI APIs to retrieve location-wise metrics and benchmark score.
* 03/18/2026 - Added Create Custom Card Time API under custom
fields section.
* 03/03/2026 - Added Response Time (overtime & by-location) and
Response Rate(overtime & by-location) APIs under reports section and
created group for Competitor AI.
* 03/02/2026 - Added sendInvite (boolean, default - true) field in
Create User Signup v2 API request body and attributes.
* 02/11/2026 - Updated the API key identifier for applicable APIs
by moving it from a query parameter to the x-api-key request header.
* 02/03/2026 - Added the "Get All QnA" API under FAQ group to
enable retrieval of QnA entries across business locations, with full
request and response documentation
* 01/19/2026 - Added a note under the Authentication and Rate
limiting section specifying that the x-api-key header is mandatory for all
API requests targeting EU region business accounts.
* 01/13/2026 - Added Create User (Signup) API under User module to
create and invite users for a business.
* 09/22/2025 - Added GMB Products APIs to onboard/connect Google
Merchant accounts and manage product listing actions.
* 08/21/2025 - Added Single main business description Support.
* 08/19/2025 - Added competitor /raptor public APIs for reviews
aggregates.
* 06/26/2025 - Added Contact V2 APIs with communication preference
flag support.
* 12/13/2024 - Added inline reply support for GetReviews APIs.
* 09/27/2024 - Added update for Google Opening Soon (BIRD-56987)
* 06/25/2024 - Updated Listings Insights API (BIRDEYE-137367)
* 05/29/2024 - Added Google Q&A Developers API Section
* 05/13/2024 - Added epoc date support for GetReviews APIs.
* 03/22/2024 - Add Update Hierarchy API (BIRD-32609)
* 03/19/2024 - Added Ticket APIs Create, Get, Update APIs under
Ticket module
* 02/26/2024 - Updated logoUrl description in Get, Update APIs
under Business module and Create, Get, Update APIs under Listing module
(BIRD-29386)
* 12/21/2023 - Add listing phase 2 api changes (BIRD-16589)
* 11/08/2023 - Add survey changes (BIRD-11944) and listing changes
(BIRD-14345)
* 11/08/2023 - Added CRUD APIs for Apple chat
* 10/15/2023 - Added CRUD APIs for Business Media.
* 10/11/2023 - Added new APIs under Listing module, Create, Update,
Get, Deactive Listings
* 09/18/2023 - Added new API under Contact module i.e, Get opt-out
contact data
* 08/25/2023 - Added new APIs under Business and Listing modules,
Get Category List API, Get GMB Attributes API & Get Timezone List
* 07/21/2023 - Added new API under Business module i.e, Business
Search API.
* 06/30/2023 - Added support for service area based information in
Get Business API and Update Business API.
* 10/04/2024 - Added support to fetch ticketId associated with the
survey responses in List Response API.
paths:
/v1/review/businessId/{businessId}:
post:
tags:
- Reviews
summary: Get Reviews
description: >-
Get Reviews returns reviews for a business account with detailed review
fields.
> __Behavior Note__
> - _If `statuses` is not provided, the API defaults to `["published"]`,
which returns featured reviews only._
> - _Status mapping: `published` = featured reviews, `parked` =
non-featured reviews._
> - _To fetch both featured and non-featured reviews, pass `statuses:
["published","parked"]` or `statuses: ["all"]` in the request body._
> - _`ratings` filters are applied only within the statuses selected for
the request._
> __Note__
> - _Deep Pagination with record window greater than 100k is not
supported. Either reduce the sindex + count to be less than equal to
100k or use appropriate filters to narrow down your result set._
operationId: getReviews
parameters:
- name: businessId
in: path
description: Id of the Business.
required: true
example: '12345678'
schema:
type: number
- name: sindex
in: query
description: >-
Start index of the reviews. Refer API note for max permissible
value.
required: true
example: '10'
schema:
type: integer
- name: count
in: query
description: >-
Number of reviews to query. Refer API note for max permissible
value.
required: true
example: '30'
schema:
type: integer
- name: includeNonAggregatedReviews
in: query
description: Include Reviews whose auto-crawling is blocked e.g. PressGaney
required: false
example: 'false'
schema:
type: boolean
- name: Accept
in: header
description: e.g. application/json
required: false
example: application/json
schema:
type: string
default: application/json
- name: x-api-key
in: header
description: >-
e.g. [Required] Partner specific API key provided by Birdeye for
data exchange.
required: false
example: >-
[Required] Partner specific API key provided by Birdeye for data
exchange.
schema:
type: string
- name: Content-Type
in: header
description: Media type of the JSON request body.
required: false
example: application/json
schema:
type: string
default: application/json
requestBody:
content:
application/json:
schema:
type: object
properties:
fromDate:
type: string
description: Review date start in UTC format.
toDate:
type: string
description: >-
Review date end in UTC format, eg if toDate is 04/01/2013,
reviews of date 04/01/2013 is excluded .
fromTimestamp:
type: number
description: >-
Review start date in milliseconds, pass either fromDate or
fromTimestamp.
toTimestamp:
type: number
description: >-
Review end date in milliseconds, pass either endDate or
toTimestamp.
updateFromDate:
type: string
description: Review updated date start in UTC format.
updateToDate:
type: string
description: Review updated date end in UTC format.
sources:
type: string
description: >-
Aggregation source name Note: use "our_website" to filter
reviews posted on Birdeye platform or use "direct_feedback"
for direct feedback.
ratings:
type: array
description: Review rating Possible values 0,1,2,3,4,5.
items: {}
searchStr:
type: string
description: String that is contained by review.
subBusinessIds:
type: array
description: BusinessIds under enterprise account.
items: {}
statuses:
type: array
description: >-
Review status filter. Valid values are "published",
"parked", and "all". If omitted, default is "published" only
(featured reviews). "published" refers to featured reviews
and "parked" refers to non-featured reviews.
items: {}
allChild:
type: boolean
description: >-
Get review from all child ignoring merge reviews flag
configured at parent/child relationship level.
tags:
type: array
description: Reviews with assigned tags
items: {}
fetchExtraParams:
type: boolean
description: >-
To fetch custom field(s) associated with the customer
attributed to the review [if any].
needCustomerInfo:
type: boolean
description: >-
To fetch customer information associated with the reviewer
[if attributed].
fetchAssitedByDetails:
type: boolean
description: >-
To retrieve employees associated with the review [if
mapped].
example:
fromTimestamp: 1712986782000
toTimestamp: 1715578782000
updateFromDate: 04/01/2013
updateToDate: 05/3/2015
sources:
- google
- citysearch
ratings:
- 1
- 2
- 3
- 4
- 5
- 0
searchStr: test string
subBusinessIds:
- 12345678
- 1232111
- 1231231321
statuses:
- all
allChild: 'true'
tags:
- positive
- negative
fetchExtraParams: false
needCustomerInfo: false
fetchAssitedByDetails: true
example:
fromTimestamp: 1712986782000
toTimestamp: 1715578782000
updateFromDate: 04/01/2013
updateToDate: 05/3/2015
sources:
- google
- citysearch
ratings:
- 1
- 2
- 3
- 4
- 5
- 0
searchStr: test string
subBusinessIds:
- 12345678
- 1232111
- 1231231321
statuses:
- all
allChild: 'true'
tags:
- positive
- negative
fetchExtraParams: false
needCustomerInfo: false
fetchAssitedByDetails: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Apiary_getReviews_Response200'
example:
- reviewId: '1858537291'
rating: 0
comments: >-
Ordered earlier today, delivered fast..exactly what I
ordered..thank you so much!
title: null
reviewer:
firstName: Sandy Rowe
lastName: Johncox
nickName: Sandy Rowe Johncox
thumbnailUrl: >-
https://ddjkm7n7lx.cloudfront.net/reviewer/dc42f6d8b2b84dc0b688c43e616.jpeg
facebookId: '638309687'
reviewURL: https://www.facebook.com/Imp-Flow-17565744/reviews
sourceType: Facebook
inlineReplyEnabled: false
reviewDate: Jan 20, 2014
response: Thanks
responseDate: Feb 18, 2014
recommended: 1
- reviewId: '73748574902'
rating: 0
comments: >-
I am a long time customer and love Dieici. I am there at
least once a week. I have never been disappointed with any
service. I love all the girls. The customer service is
beyond a 10. I also love the new addition Wish to the salon!
Wish is a woman's clothing boutique. What could be
better...beauty and fashion all in one spot!!! Dieci keeps
getting better and better!
title: null
reviewer:
firstName: Jennifer
lastName: Bennett
nickName: Jennifer Bennett
thumbnailUrl: >-
http://d2xt3xymj142xp.cloudfront.net/reviewer/9a070cf98f014f5d9b06987dcc9c48fe.jpeg
emailId: jbennett@gmail.com
facebookId: null
city: Cedar Knolls
state: ' NJ'
reviewUrl: https://birdeye.com/imp-flower-15229573096
sourceType: Direct Feedback
inlineReplyEnabled: true
reviewDate: Jan 20, 2019
response: Thanks
responseDate: Feb 18, 2019
featured: 0
customerId: 7432167
extraParams:
key1: value1
key2: value2
key3: value3
assitedByUser:
- firstName: Steve
lastName: M.
emailId: steve@test.com
phoneNum: ''
- firstName: Smith
lastName: S.
emailId: smith@test.com
phoneNum: ''
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/1163Model'
x-apiary-response-models:
- $ref: '#/components/schemas/1163Model'
- $ref: '#/components/schemas/1167Model'
- $ref: '#/components/schemas/1186Model'
- $ref: '#/components/schemas/1187Model'
- $ref: '#/components/schemas/1227Model'
- $ref: '#/components/schemas/1228Model'
- $ref: '#/components/schemas/1244Model'
x-apiary-response-examples:
error_1163:
value:
code: 1163
message: Invalid start index value
error_1167:
value:
code: 1167
message: API key is missing
error_1186:
value:
code: 1186
message: Invalid from date. Allowed format is "MM/dd/yyyy".
error_1187:
value:
code: 1187
message: Invalid to date. Allowed format is "MM/dd/yyyy".
error_1227:
value:
code: 1227
message: Invalid updated from date. Allowed format is MM/dd/yyyy
error_1228:
value:
code: 1228
message: Invalid updated to date. Allowed format is MM/dd/yyyy
error_1244:
value:
code: 1244
message: Maximum 5 keywords can be selected for filter.
examples:
response:
value:
code: 1163
message: Invalid start index value
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/1161Model'
x-apiary-response-models:
- $ref: '#/components/schemas/1161Model'
- $ref: '#/components/schemas/1164Model'
x-apiary-response-examples:
error_1161:
value:
code: 1161
message: Invalid API key
error_1164:
value:
code: 1164
message: Invalid result count value
examples:
response:
value:
code: 1161
message: Invalid API key
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/1011Model'
examples:
response:
value:
code: 1011
message: Business id is invalid
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/89Model'
examples:
response:
value:
code: 89
message: Rate limit exceeded
components:
schemas:
Apiary_getReviews_Response200:
type: array
items:
type: object
properties:
reviewId:
type: number
description: Id of the review.
rating:
type: number
description: >-
Overall rating for the review, in case of direct feedback and
facebook recommendations it will be 0. For Facebook
recommendations, value will be 1, Non recommended review will have
value set as 0.
comments:
type: string
description: User comment.
reviewer:
type: object
properties:
firstName:
type: string
description: Reviewer first name.
lastName:
type: string
description: Reviewer last name.
nickName:
type: string
description: Reviewer full name.
thumbnailUrl:
type: string
description: Thumbnail URL
description: Reviewer details
sourceType:
type: string
description: Source of the review if it is an aggregated review.
reviewURL:
type: string
description: Review url
reviewDate:
type: string
description: Review posted date.
response:
type: string
description: Review response text.
responseDate:
type: string
description: Response date.
inlineReplyEnabled:
type: boolean
description: If true, you can post replies through the dashboard.
enableReply:
type: boolean
description: Whether a review reply is supported via Birdeye API or not.
customerId:
type: number
description: Customer's Id attributed with this review (if any).
extraParams:
type: object
description: >-
Key value pair of custom field(s) associated with the customer
attributed to the review (if any)
assitedByUser:
type: object
properties:
firstName:
type: string
description: Employee first name.
lastName:
type: string
description: Employee last name.
emailId:
type: string
description: Employee email id.
phoneNum:
type: string
description: Employee phone number.
description: Employees associated with the review
1163Model:
type: object
properties:
code:
type: number
message:
type: string
example:
code: 1163
message: Invalid start index value
1161Model:
type: object
properties:
code:
type: number
message:
type: string
example:
code: 1161
message: Invalid API key
1011Model:
type: object
properties:
code:
type: number
message:
type: string
example:
code: 1011
message: Business id is invalid
89Model:
type: object
properties:
code:
type: number
message:
type: string
example:
code: 89
message: Rate limit exceeded
````