Keep your business information accurate and consistent across 50+ websites.
openapi: 3.1.0
info:
title: Birdeye Aggregation Listing API
description: RESTful API for managing online reviews, sending survey requests, responding to customer messages, automating review collection workflows, and tracking reputation metrics across multiple business locations.
version: 1.0.0
termsOfService: https://birdeye.com/terms-of-service/
contact:
url: https://developers.birdeye.com/
servers:
- url: https://api.birdeye.com
description: Production
security:
- apiKey: []
tags:
- name: Listing
description: Keep your business information accurate and consistent across 50+ websites.
paths:
/v1/listing/fix:
post:
summary: Fix Listing
operationId: fix-listing
tags:
- Listing
parameters:
- name: b_id
in: query
required: true
description: Id of the business.
schema:
type: number
example: '12345678'
responses:
'200':
description: HTTP 200 response
content:
application/json:
schema:
type: object
example:
code: 1175
message: No business found with the given id
requestBody:
required: true
content:
application/json:
schema:
type: object
example: {}
/v1/listing/status/location:
get:
summary: Get Location Status Report
operationId: get-location-status-report
tags:
- Listing
parameters:
- name: businessNumber
in: query
required: true
description: Id of the business.
schema:
type: number
example: '169744180007807'
responses:
'200':
description: HTTP 200 response
content:
application/json:
schema:
type: object
example:
code: 1043
message: Business should be either SMB or Enterprise sub account
/v1/listing/insights:
post:
summary: Listings Insights
operationId: listings-insights
tags:
- Listing
parameters:
- name: businessId
in: query
required: true
description: Id of the account.
schema:
type: number
example: '12345678'
responses:
'200':
description: HTTP 200 response
content:
application/json:
schema:
type: object
example:
code: 1175
message: No business found with the given id
requestBody:
required: true
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema#
type: object
properties:
businessNumbers:
type: array
startDate:
type: string
endDate:
type: string
viewMode:
type: array
required:
- viewMode
/v1/listing/report/{reportType}/datapoints:
post:
summary: Listings Insights Datapoints
operationId: listings-insights-datapoints
tags:
- Listing
parameters:
- name: reportType
in: path
required: true
description: Report type, Possible values [google_view_search_map, gmb_customer_actions_map, fb_users_reached,fb_users_engaged, bing_impression_count,bing_customer_actions]
schema:
type: string
example: google_view_search_map
- name: businessId
in: query
required: true
description: Id of the account.
schema:
type: number
example: '12345678'
responses:
'200':
description: HTTP 200 response
content:
application/json:
schema:
type: object
example:
code: 1175
message: No business found with the given id
requestBody:
required: true
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema#
type: object
properties:
businessNumbers:
type: array
startDate:
type: string
endDate:
type: string
viewMode:
type: array
groupByType:
type: string
/v1/listing/{businessNumber}/gmb-attributes-list:
get:
summary: Get GMB Attributes
operationId: get-gmb-attributes
tags:
- Listing
parameters:
- name: businessNumber
in: path
required: true
description: Business Number.
schema:
type: number
example: '169744180007807'
- name: categoryId
in: query
required: true
description: Category id.
schema:
type: string
example: gcid:electrical_installation_service
- name: countryCode
in: query
required: true
description: Code of the country, Possible values are US,CA,AU,PR,NZ,MX,IN,UK,FR,IT.
schema:
type: string
example: US
responses:
'200':
description: HTTP 200 response
content:
application/json:
schema:
type: object
example:
code: 2286
message: Invalid whatsapp business link
/v1/listing/{businessNumber}/apple-location-attributes-list:
get:
summary: Get Apple Attributes
operationId: get-apple-attributes
tags:
- Listing
parameters:
- name: businessNumber
in: path
required: true
description: Business Number.
schema:
type: number
example: '169744180007807'
responses:
'200':
description: HTTP 200 response
content:
application/json:
schema:
type: object
example:
code: 400
message: Invalid country code
/v1/listing/{businessNumber}/apple-action-links:
get:
summary: Get Apple Action Links
operationId: get-apple-action-links
tags:
- Listing
parameters:
- name: businessNumber
in: path
required: true
description: Business Number.
schema:
type: number
example: '169744180007807'
responses:
'200':
description: HTTP 200 response
content:
application/json:
schema:
type: object
example:
code: 400
message: Invalid country code
/v1/listing/{businessNumber}/category-list:
get:
summary: Get Category List
operationId: get-category-list
tags:
- Listing
parameters:
- name: businessNumber
in: path
required: true
description: Business Number.
schema:
type: number
example: '169744180007807'
- name: sourceName
in: query
required: true
description: Source name for which category data needs to be fetched. Possible values are BING, HEALTHCARE, GMB, VENDOR, FACEBOOK, APPLE.
schema:
type: string
example: BING
- name: countryCode
in: query
required: true
description: Code of the country, Possible values are US,CA,AU,PR,NZ,MX,IN,UK,FR,IT.
schema:
type: string
example: US
responses:
'200':
description: HTTP 200 response
content:
application/json:
schema:
type: object
example:
code: 400
message: Invalid Source Name
/v1/listing/{businessNumber}/create:
post:
summary: Create Listing
operationId: create-listing
tags:
- Listing
parameters:
- name: businessNumber
in: path
required: true
description: Business Number.
schema:
type: number
example: '169744180007807'
responses:
'200':
description: HTTP 200 response
content:
application/json:
schema:
type: object
example:
code: 6001
message: The 'sub_locality' field cannot exceed 80 characters.
requestBody:
required: true
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema#
type: object
properties:
businessInfo:
type: object
properties:
name:
type: string
phone:
type: string
websiteUrl:
type: string
emailId:
type: string
isAddressHidden:
type: string
isServiceAreaProvider:
type: string
mainBusinessDescription:
type: string
serviceAreas:
type: array
location:
type: object
properties:
address1:
type: string
address2:
type: string
city:
type: string
state:
type: string
countryCode:
type: string
zip:
type: string
subLocality:
type: string
required:
- zip
required:
- name
- phone
additionalInfo:
type: object
properties:
establishedYear:
type: number
timezone:
type: string
languages:
type: array
moreHours:
type: array
appleMoreHours:
type: array
wholeWeekOperating:
type: number
hoursOfOperations:
type: array
specialHours:
type: array
businessStatus:
type: string
reopenDate:
type: string
services:
type: string
keywords:
type: string
products:
type: string
appointmentLink:
type: string
reservationLink:
type: string
menuLink:
type: string
orderAheadLink:
type: string
impressum:
type: string
paymentTypes:
type: array
additionalPaymentTypes:
type: string
localPhoneNumber:
type: string
tollFreePhoneNumber:
type: string
androidAppURL:
type: string
iosAppURL:
type: string
required:
- hoursOfOperations
- services
media:
type: object
properties:
logoUrl:
type: string
coverImageUrl:
type: string
gmbCover:
type: string
facebookCover:
type: string
optOut:
type: object
properties:
gmbLogoOptOut:
type: boolean
fbLogoOptOut:
type: boolean
gmbCoverOptOut:
type: boolean
fbCoverOptOut:
type: boolean
gmbProfileOptOut:
type: boolean
businessProfileOptOut:
type: boolean
covidInfo:
type: object
properties:
postDescription:
type: string
covid19SupportLink:
type: string
virtualCareLink:
type: string
bingListing:
type: object
properties:
primaryCategoryBing:
type: string
bingCategories:
type: array
bingPhoneNumber:
type: string
bingDescription:
type: string
internalListing:
type: object
properties:
description:
type: string
category:
type: string
subCategories:
type: array
displayCategory:
type: string
required:
- description
- category
- subCategories
facebookListing:
type: object
properties:
facebookPhoneNumber:
type: string
categories:
type: array
facebookDescription:
type: string
gmbListing:
type: object
properties:
googleWebsiteUrl:
type: string
googlePhoneNumber:
type: string
googleStoreId:
type: string
primaryCategoryGmb:
type: string
additionalCategories:
type: array
googleDescription:
type: string
attributes:
type: object
foodDelivery:
type: string
foodTakeout:
type: string
whatsappBusinessLink:
type: string
textMessageNumber:
type: string
appleListing:
type: object
properties:
phoneNumber:
type: string
appleWebsiteUrl:
type: string
primaryCategory:
type: string
additionalCategories:
type: array
appleLocationAttributes:
type: object
appleActionLinks:
type: object
appleBusinessName:
type: string
appleBusinessDescription:
type: string
thirdPartyListing:
type: object
properties:
thirdPartyCategory:
type: string
thirdPartySubCategories:
type: string
socialProfileURLs:
type: object
properties:
facebookUrl:
type: string
twitterUrl:
type: string
linkedInUrl:
type: string
googleUrl:
type: string
youTubeUrl:
type: string
instagramUrl:
type: string
pintrestUrl:
type: string
bbbUrl:
type: string
lendingtreeUrl:
type: string
healthcare:
type: object
properties:
doctorCategories:
type: string
isProvider:
type: boolean
practiceName:
type: string
firstName:
type: string
middleName:
type: string
surName:
type: string
npi:
type: number
credentials:
type: string
university:
type: string
hospitalAffiliations:
type: string
insurancesAccepted:
type: string
/v1/listing/{businessNumber}/update:
put:
summary: Update Listing
operationId: update-listing
tags:
- Listing
parameters:
- name: businessNumber
in: path
required: true
description: Business Number.
schema:
type: number
example: '169744180007807'
responses:
'200':
description: HTTP 200 response
content:
application/json:
schema:
type: object
example:
code: 6001
message: The 'sub_locality' field cannot exceed 80 characters.
requestBody:
required: true
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema#
type: object
properties:
businessInfo:
type: object
properties:
name:
type: string
phone:
type: string
websiteUrl:
type: string
emailId:
type: string
isAddressHidden:
type: string
isServiceAreaProvider:
type: string
mainBusinessDescription:
type: string
serviceAreas:
type: array
location:
type: object
properties:
address1:
type: string
address2:
type: string
city:
type: string
state:
type: string
countryCode:
type: string
zip:
type: string
subLocality:
type: string
required:
- zip
required:
- name
- phone
additionalInfo:
type: object
properties:
establishedYear:
type: number
timezone:
type: string
languages:
type: array
moreHours:
type: array
appleMoreHours:
type: array
wholeWeekOperating:
type: number
hoursOfOperations:
type: array
specialHours:
type: array
businessStatus:
type: string
reopenDate:
type: string
services:
type: string
keywords:
type: string
products:
type: string
appointmentLink:
type: string
reservationLink:
type: string
menuLink:
type: string
orderAheadLink:
type: string
impressum:
type: string
paymentTypes:
type: array
additionalPaymentTypes:
type: string
localPhoneNumber:
type: string
tollFreePhoneNumber:
type: string
androidAppURL:
type: string
iosAppURL:
type: string
required:
- hoursOfOperations
- services
media:
type: object
properties:
logoUrl:
type: string
coverImageUrl:
type: string
gmbCover:
type: string
facebookCover:
type: string
optOut:
type: object
properties:
gmbLogoOptOut:
type: boolean
fbLogoOptOut:
type: boolean
gmbCoverOptOut:
type: boolean
fbCoverOptOut:
type: boolean
gmbProfileOptOut:
type: boolean
businessProfileOptOut:
type: boolean
covidInfo:
type: object
properties:
postDescription:
type: string
covid19SupportLink:
type: string
virtualCareLink:
type: string
bingListing:
type: object
properties:
primaryCategoryBing:
type: string
bingCategories:
type: array
bingPhoneNumber:
type: string
bingDescription:
type: string
internalListing:
type: object
properties:
description:
type: string
category:
type: string
subCategories:
type: array
displayCategory:
type: string
required:
- description
- category
- subCategories
facebookListing:
type: object
properties:
facebookPhoneNumber:
type: string
categories:
type: array
facebookDescription:
type: string
gmbListing:
type: object
properties:
googleWebsiteUrl:
type: string
googlePhoneNumber:
type: string
googleStoreId:
type: string
primaryCategoryGmb:
type: string
additionalCategories:
type: array
googleDescription:
type: string
attributes:
type: object
foodDelivery:
type: string
foodTakeout:
type: string
whatsappBusinessLink:
type: string
textMessageNumber:
type: string
appleListing:
type: object
properties:
phoneNumber:
type: string
appleWebsiteUrl:
type: string
primaryCategory:
type: string
additionalCategories:
type: array
appleLocationAttributes:
type: object
appleActionLinks:
type: object
appleBusinessName:
type: string
appleBusinessDescription:
type: string
thirdPartyListing:
type: object
properties:
thirdPartyCategory:
type: string
thirdPartySubCategories:
type: string
socialProfileURLs:
type: object
properties:
facebookUrl:
type: string
twitterUrl:
type: string
linkedInUrl:
type: string
googleUrl:
type: string
youTubeUrl:
type: string
instagramUrl:
type: string
pintrestUrl:
type: string
bbbUrl:
type: string
lendingtreeUrl:
type: string
healthcare:
type: object
properties:
doctorCategories:
type: string
isProvider:
type: boolean
practiceName:
type: string
firstName:
type: string
middleName:
type: string
surName:
type: string
npi:
type: number
credentials:
type: string
university:
type: string
hospitalAffiliations:
type: string
insurancesAccepted:
type: string
/v1/listing/{businessNumber}/get:
get:
summary: Get Listing
operationId: get-listing
tags:
- Listing
parameters:
- name: businessNumber
in: path
required: true
description: Business Number.
schema:
type: number
example: '169744180007807'
responses:
'200':
description: HTTP 200 response
content:
application/json:
schema:
type: object
example:
code: 89
message: Rate limit exceeded
/v1/listing/{businessNumber}/more-hours-type:
get:
summary: Get More Hours Type
operationId: get-more-hours-type
tags:
- Listing
parameters:
- name: businessNumber
in: path
required: true
description: Business Number.
schema:
type: number
example: '169744180007807'
- name: channel
in: query
required: true
description: Source name for which more hours type needs to be fetched. Possible values are gmb, apple. Default value will be gmb if not passed
schema:
type: string
example: gmb
responses:
'200':
description: HTTP 200 response
content:
application/json:
schema:
type: object
example:
code: 400
message: Invalid Source Name
/v1/listing/{businessNumber}/gmb/keywords:
post:
summary: Get Google Keywords Count
operationId: get-google-keywords-count
tags:
- Listing
parameters:
- name: businessNumber
in: path
required: true
description: Account Business Number.
schema:
type: string
example: '169744180007807'
responses:
'200':
description: HTTP 200 response
content:
application/json:
schema:
type: object
example:
code: 2458
message: Invalid order value. Allowed values are 'asc' or 'desc'.
requestBody:
required: true
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema#
type: object
properties:
selectedMonth:
type: array
selectedkeywords:
type: array
keywordsSearch:
type: string
limit:
type: number
startIndex:
type: number
sortby:
type: string
order:
type: string
businessNumbers:
type: array
required:
- selectedMonth
/v1/listing/{businessNumber}/deactivate:
post:
summary: Deactivate Listing
operationId: deactivate-listing
tags:
- Listing
parameters:
- name: businessNumber
in: path
required: true
description: Business Number.
schema:
type: number
example: '169744180007807'
responses:
'200':
description: HTTP 200 response
content:
application/json:
schema:
type: object
example:
code: 89
message: Rate limit exceeded
/v1/listing/menu-details:
post:
summary: Retrieve Menu Details
operationId: retrieve-menu-details
tags:
- Listing
parameters: []
responses:
'200':
description: HTTP 200 response
content:
application/json:
schema:
type: object
example:
code: 2458
message: Invalid order value. Allowed values are 'asc' or 'desc'.
requestBody:
required: true
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema#
type: object
properties:
businessNumbers:
type: array
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: Partner specific API key provided by Birdeye for data exchange.