Birdeye API

openapi: 3.1.0
info:
  title: Birdeye 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: []
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Partner specific API key provided by Birdeye for data exchange.
paths:
  /v1/signup/reseller/subaccount:
    post:
      summary: Create a business
      operationId: create-a-business
      tags:
      - Business
      parameters:
      - name: rid
        in: query
        required: true
        description: Id of the Reseller.
        schema:
          type: number
        example: '12334667201'
      - name: email_id
        in: query
        required: true
        description: Business Email id.
        schema:
          type: string
        example: sample@birdeye.com
      responses:
        '200':
          description: HTTP 200 response
          content:
            application/json:
              schema:
                type: object
                example:
                  code: 2166
                  message: Invalid Business Type
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $schema: http://json-schema.org/draft-07/schema#
              type: object
              properties:
                businessName:
                  type: string
                zip:
                  type: string
                type:
                  type: string
                phone:
                  type: number
                entityCategory:
                  type: string
                countryCode:
                  type: string
                aggrOptions:
                  type: number
              required:
              - businessName
              - zip
              - phone
  /v1/business/{businessNumber}/search:
    post:
      summary: Search Business
      operationId: search-business
      tags:
      - Business
      parameters:
      - name: businessNumber
        in: path
        required: true
        description: Long id of the business, under which user wants to search for.
        schema:
          type: number
        example: '169744180007807'
      responses:
        '200':
          description: HTTP 200 response
          content:
            application/json:
              schema:
                type: object
                example:
                  code: 400
                  message: Page size must not be less than one!
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $schema: http://json-schema.org/draft-07/schema#
              type: object
              properties:
                searchStr:
                  type: string
                sortBy:
                  type: string
                sortOrder:
                  type: string
                startIndex:
                  type: number
                pageSize:
                  type: number
  /v1/business/{business_id}:
    get:
      summary: Get Business
      operationId: get-business
      tags:
      - Business
      parameters:
      - name: business_id
        in: path
        required: true
        description: Id of the Business.
        schema:
          type: string
        example: '12345678'
      responses:
        '200':
          description: HTTP 200 response
          content:
            application/json:
              schema:
                type: object
                example:
                  code: 1167
                  message: API key is missing
  /v1/business/{businessId}:
    put:
      summary: Update Business
      operationId: update-business
      tags:
      - Business
      parameters:
      - name: businessId
        in: path
        required: true
        description: The Business Number
        schema:
          type: string
        example: '12345678'
      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:
                name:
                  type: string
                alias:
                  type: string
                isAddressHidden:
                  type: number
                location:
                  type: object
                  properties:
                    address1:
                      type: string
                    address2:
                      type: string
                    subLocality:
                      type: string
                    city:
                      type: string
                    state:
                      type: string
                    countryCode:
                      type: string
                    zip:
                      type: string
                  required:
                  - zip
                emailId:
                  type: string
                phone:
                  type: string
                fax:
                  type: string
                websiteUrl:
                  type: string
                establishedYear:
                  type: number
                timezone:
                  type: string
                languages:
                  type: array
                isServiceAreaProvider:
                  type: string
                serviceAreas:
                  type: array
                working24x7:
                  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
                payment:
                  type: string
                localPhoneNumber:
                  type: string
                tollFreePhoneNumber:
                  type: string
                androidAppURL:
                  type: string
                iosAppURL:
                  type: string
                logoUrl:
                  type: string
                gmbLogoOptOut:
                  type: number
                fbLogoOptOut:
                  type: number
                gmbCoverOptOut:
                  type: number
                fbCoverOptOut:
                  type: number
                coverImageUrl:
                  type: string
                gmbCover:
                  type: string
                facebookCover:
                  type: string
                coverBusinessInfoLayout:
                  type: string
                covidInfo:
                  type: object
                  properties:
                    postDescription:
                      type: string
                    covid19SupportLink:
                      type: string
                    virtualCareLink:
                      type: string
                bingListing:
                  type: object
                  properties:
                    primaryCategoryBing:
                      type: string
                    bingPhoneNumber:
                      type: string
                    categories:
                      type: string
                    bingDescription:
                      type: string
                internalListing:
                  type: object
                  properties:
                    description:
                      type: string
                    category:
                      type: string
                    subcategory:
                      type: string
                    displayCategory:
                      type: string
                  required:
                  - category
                  - subcategory
                facebookListing:
                  type: object
                  properties:
                    category:
                      type: string
                    facebookDescription:
                      type: string
                    facebookPhoneNumber:
                      type: string
                gmbListing:
                  type: object
                  properties:
                    googleWebsiteUrl:
                      type: string
                    googlePhoneNumber:
                      type: string
                    googleStoreId:
                      type: string
                    primaryCategoryGmb:
                      type: string
                    additionalCategory:
                      type: string
                    googleDescription:
                      type: string
                    attributes:
                      type: object
                    foodDelivery:
                      type: string
                    foodTakeout:
                      type: string
                socialProfileURLs:
                  type: object
                  properties:
                    facebookUrl:
                      type: string
                    twitterUrl:
                      type: string
                    linkedInUrl:
                      type: string
                    googleUrl:
                      type: string
                    youTubeUrl:
                      type: string
                isSEOEnabled:
                  type: boolean
                externalReferenceId:
                  type: string
                customFields:
                  type: object
                  properties:
                    type:
                      type: string
                    fieldValue:
                      type: string
                    fieldName:
                      type: string
                    id:
                      type: number
                  required:
                  - fieldName
                  - id
                entityCategory:
                  type: string
              required:
              - emailId
              - phone
              - services
  /v1/business/{business_Id}:
    delete:
      summary: Delete Business
      operationId: delete-business
      tags:
      - Business
      parameters:
      - name: business_Id
        in: path
        required: true
        description: Id of the Business.
        schema:
          type: string
        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
  /v1/business/{business_id}/status:
    put:
      summary: Update the status
      operationId: update-the-status
      tags:
      - Business
      parameters:
      - name: business_id
        in: path
        required: true
        description: Business id whose status has to be changed. Returned by create
          business API
        schema:
          type: string
        example: '12345678'
      - name: astatus
        in: query
        required: true
        description: New status for the business. Valid values are "active/inactive".
        schema:
          type: string
        example: inactive
      responses:
        '200':
          description: HTTP 200 response
          content:
            application/json:
              schema:
                type: object
                example:
                  code: 1191
                  message: Invalid status.
  /v1/business/child/all:
    get:
      summary: Get Child Businesses
      operationId: get-child-businesses
      tags:
      - Business
      parameters:
      - name: pid
        in: query
        required: true
        description: Reseller/Sub-reseller/Enterprise Id.
        schema:
          type: number
        example: '12345678'
      responses:
        '200':
          description: HTTP 200 response
          content:
            application/json:
              schema:
                $schema: http://json-schema.org/draft-07/schema#
                type: array
  /v1/business/tabs:
    post:
      summary: Update public profile of Businesses
      operationId: update-public-profile-of-businesses
      tags:
      - Business
      parameters:
      - name: businessId
        in: query
        required: true
        description: Id of the Business.
        schema:
          type: string
        example: '12345678'
      responses:
        '200':
          description: HTTP 200 response
          content:
            application/json:
              schema:
                type: object
                example:
                  code: 1191
                  message: Invalid status.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $schema: http://json-schema.org/draft-07/schema#
              type: object
              properties:
                profileTabs:
                  type: array
  /v1/business/{businessId}/hierarchy:
    get:
      summary: Get hierarchy for an enterprise
      operationId: get-hierarchy-for-an-enterprise
      tags:
      - Business
      parameters:
      - name: businessId
        in: path
        required: true
        description: Id of the Business.
        schema:
          type: string
        example: '12345678'
      responses:
        '200':
          description: HTTP 200 response
          content:
            application/json:
              schema:
                type: object
                example:
                  code: 1167
                  message: API key is missing
  /v1/business/business-hierarchy/location/update-mapping/{businessId}:
    post:
      summary: Update Hierarchy
      operationId: update-hierarchy
      tags:
      - Business
      parameters:
      - name: businessId
        in: path
        required: true
        description: Id of the Business.
        schema:
          type: string
        example: '12345678'
      responses:
        '200':
          description: HTTP 200 response
          content:
            application/json:
              schema:
                type: object
                example:
                  code: 1011
                  message: Business id is invalid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $schema: http://json-schema.org/draft-07/schema#
              type: object
              properties:
                Level:
                  type: string
  /v1/business/{businessNumber}/profile/customcard:
    get:
      summary: Get Custom card details
      operationId: get-custom-card-details
      tags:
      - Business
      parameters:
      - name: businessNumber
        in: path
        required: true
        description: Id of a business (Long).
        schema:
          type: number
      responses:
        '200':
          description: HTTP 200 response
          content:
            application/json:
              schema:
                type: object
                example:
                  code: 1011
                  message: Business id is invalid
  /v1/business/public/card/{cardId}:
    put:
      summary: Update Custom card
      operationId: update-custom-card
      tags:
      - Business
      parameters:
      - name: cardId
        in: path
        required: true
        description: Id of the custom card to update.
        schema:
          type: number
      responses:
        '200':
          description: HTTP 200 response
          content:
            application/json:
              schema:
                type: object
                example:
                  code: 1011
                  message: Business id is invalid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $schema: http://json-schema.org/draft-07/schema#
              type: object
              properties:
                cardId:
                  type: number
                title:
                  type: string
                description:
                  type: string
                imageURL:
                  type: string
                imagePosition:
                  type: string
                isVisible:
                  type: number
                isPinOnTop:
                  type: number
                clickURL:
                  type: string
                linkText:
                  type: string
                type:
                  type: string
              required:
              - cardId
              - title
    delete:
      summary: Delete Custom card
      operationId: delete-custom-card
      tags:
      - Business
      parameters:
      - name: cardId
        in: path
        required: true
        description: Id of the custom card to delete.
        schema:
          type: number
      responses:
        '200':
          description: HTTP 200 response
          content:
            application/json:
              schema:
                type: object
                example:
                  code: 1011
                  message: Business id is invalid
  /v1/business/{businessNumber}/timezones:
    get:
      summary: Get Timezone List
      operationId: get-timezone-list
      tags:
      - Business
      parameters:
      - name: businessNumber
        in: path
        required: true
        description: Id of a business (Long).
        schema:
          type: number
      responses:
        '200':
          description: HTTP 200 response
          content:
            application/json:
              schema:
                type: object
                example:
                  code: 1011
                  message: Business id is invalid
  /v1/business/{businessNumber}/birdeye/impressions:
    post:
      summary: Get Birdeye Impressions
      operationId: get-birdeye-impressions
      tags:
      - Business
      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: 1167
                  message: API key is missing
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $schema: http://json-schema.org/draft-07/schema#
              type: object
              properties:
                businessNumbers:
                  type: string
                startDate:
                  type: string
                endDate:
                  type: string
                limit:
                  type: number
                startIndex:
                  type: number
                sortby:
                  type: string
                order:
                  type: string
              required:
              - businessNumbers
  /v1/business/public/custom-fields/create:
    post:
      summary: Create
      operationId: create
      tags:
      - Custom Fields
      parameters: []
      responses:
        '200':
          description: HTTP 200 response
          content:
            application/json:
              schema:
                type: object
                example:
                  code: 5040
                  message: Max limit reached for custom fields.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $schema: http://json-schema.org/draft-07/schema#
              type: object
              properties:
                defaultValue:
                  type: string
                dropDownOptions:
                  type: array
                fieldDescription:
                  type: string
                fieldName:
                  type: string
                filterable:
                  type: boolean
                type:
                  type: string
              required:
              - fieldName
              - type
  /v1/business/public/custom-fields/update/{fieldId}:
    put:
      summary: Update
      operationId: update
      tags:
      - Custom Fields
      parameters:
      - name: fieldId
        in: path
        required: true
        description: fieldId of the custom field created earlier.
        schema:
          type: number
        example: '376'
      responses:
        '200':
          description: HTTP 200 response
          content:
            application/json:
              schema:
                type: object
                example:
                  code: 5026
                  message: Custom field updation failed.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $schema: http://json-schema.org/draft-07/schema#
              type: object
              properties:
                defaultValue:
                  type: string
                dropDownOptions:
                  type: array
                fieldDescription:
                  type: string
                filterable:
                  type: boolean
                isHidden:
                  type: boolean
  /v1/business/public/custom-fields/get/{fieldId}?locationBizNumber={locationBizNumber}:
    get:
      summary: Get
      operationId: get
      tags:
      - Custom Fields
      parameters:
      - name: fieldId
        in: path
        required: true
        description: fieldId of the custom field created earlier.
        schema:
          type: number
        example: '376'
      - name: locationBizNumber
        in: path
        required: true
        description: Long Location number of the Location
        schema:
          type: number
        example: '123456789'
      responses:
        '200':
          description: HTTP 200 response
          content:
            application/json:
              schema:
                type: object
                example:
                  code: 5025
                  message: Custom field not found.
  /v1/business/public/custom-fields/getList?locationBizNumber={locationBizNumber}:
    post:
      summary: POST
      operationId: post
      tags:
      - Custom Fields
      parameters:
      - name: locationBizNumber
        in: path
        required: true
        description: Long Location number of the Location.
        schema:
          type: number
        example: '123456789'
      responses:
        '200':
          description: HTTP 200 response
          content:
            application/json:
              schema:
                type: object
                example:
                  code: 1027
                  message: Invalid business number.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $schema: http://json-schema.org/draft-07/schema#
              type: object
              properties:
                page:
                  type: number
                size:
                  type: number
                searchStr:
                  type: string
                sortBy:
                  type: string
                orderBy:
                  type: string
              required:
              - page
              - size
  /v1/business/public/custom-fields/delete/{fieldId}:
    delete:
      summary: Delete
      operationId: delete
      tags:
      - Custom Fields
      parameters:
      - name: fieldId
        in: path
        required: true
        description: fieldId of the custom field created earlier.
        schema:
          type: number
        example: '376'
      responses:
        '200':
          description: HTTP 200 response
          content:
            application/json:
              schema:
                type: object
                example:
                  code: 5028
                  message: Custom field delete failed.
  /v1/business/public/custom-fields/associate:
    put:
      summary: Associate
      operationId: associate
      tags:
      - Custom Fields
      parameters: []
      responses:
        '200':
          description: HTTP 200 response
          content:
            application/json:
              schema:
                type: object
                example:
                  code: 5028
                  message: Custom field delete failed.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $schema: http://json-schema.org/draft-07/schema#
              type: object
              properties:
                fieldId:
                  type: number
                fieldValue:
                  type: string
                businessNumber:
                  type: number
              required:
              - fieldId
              - fieldValue
              - businessNumber
  /v1/business/public/card:
    post:
      summary: Create Custom card
      operationId: create-custom-card
      tags:
      - Custom Fields
      parameters: []
      responses:
        '200':
          description: HTTP 200 response
          content:
            application/json:
              schema:
                type: object
                example:
                  code: 1011
                  message: Business id is invalid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $schema: http://json-schema.org/draft-07/schema#
              type: object
              properties:
                title:
                  type: string
                description:
                  type: string
                imageURL:
                  type: string
                imagePosition:
                  type: number
                isVisible:
                  type: number
                isPinOnTop:
                  type: number
                clickURL:
                  type: string
              required:
              - title
  /v1/user/signup/v2:
    post:
      summary: Create User
      operationId: create-user
      tags:
      - User
      parameters: []
      responses:
        '200':
          description: HTTP 200 response
          content:
            application/json:
              schema:
                type: object
                example:
                  code: 1059
                  message: Last name cannot be more than 50 characters
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $schema: http://json-schema.org/draft-07/schema#
              type: object
              properties:
                firstName:
                  type: string
                lastName:
                  type: string
                userEmailId:
                  type: string
                phone:
                  type: string
                userRole:
                  type: string
                sendInvite:
                  type: boolean
              required:
              - userEmailId
              - userRole
  /v1/user/updateUser:
    put:
      summary: Update User
      operationId: update-user
      tags:
      - User
      parameters:
      - name: userEmailId
        in: query
        required: true
        description: Email id of the user to be updated
        schema:
          type: string
        example: abc@test.com
      - name: entUser
        in: query
        required: true
        description: 'true if the user needs to provide enterprise level access in
          case of all locations.

          entUser needs to be passed as true if user needs to be provided access to
          all locations otherwise by default its false.'
        schema:
          type: boolean
        example: 'false'
      responses:
        '200':
          description: HTTP 200 response
          content:
            application/json:
              schema:
                type: object
                example:
                  code: 1189
                  message: User with given email id not found.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $schema: http://json-schema.org/draft-07/schema#
              type: object
              properties:
                locationsNumberAccess:
                  type: array
                user:
                  type: object
                  properties:
                    firstName:
                      type: string
                    lastName:
                      type: string
                userRole:
                  type: string
                notification:
                  type: object
                  properties:
                    sendReviewEmailAlert:
                      type: number
                    sendDailyReviewDigest:
                      type: number
                    dailyDigestAbsoluteTime:
                      type: string
                    dailyDigestRunHour:
                      type: number
                    dailyDigestRunMinute:
                      type: number
                    sendWeeklyReviewDigest:
                      type: number
                    weeklyDigestAbsoluteTime:
                      type: string
                    weeklyDigestRunDay:
                      type: number
                    weeklyDigestRunHour:
                      type: number
                    weeklyDigestRunMinute:
                      type: number
                    sendReviewSmsAlert:
                      type: number
                    sendDailySocialDigest:
                      type: number
                    sendTicketAlert:
                      type: number
                    sendTicketStatusAlert:
                      type: number
                    sendTicketAssigneeChangeAlert:
                      type: number
                    sendTicketCommentAlert:
                      type: number
                    sendTicketStartOrStoppedWatchingAlert:
                      type: number
                    sendSurveyAlert:
                      type: number
                    sendReferralAlert:
                      type: number
                    sendScanToolSignUpAlert:
                      type: number
                    webChatEmailInterval:
                      type: string
                    webChatEmailAbsoluteTime:
                      type: string
                    enableWebchat:
                      type: number
                    enableTeamAlert:
                      type: number
                    reviewAlertRatings:
                      type: array
                    messengerEmailConversationType:
                      type: string
                    assignedToMeAlert:
                      type: number
                    enableBrowserNotification:
                      type: number
                    messengerReportEnable:
                      type: number
                    appointmentBooking:
                      type: number
                    appointmentFormsEnabled:
                      type: number
                    enableAIPostSuggestions:
                      type: number
                    enablePostFailureEmail:
                      type: number
                    enableDirectMessageEmail:
                      type: number
                    enablePostCommentsEmail:
                      type: numb

# --- truncated at 32 KB (214 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/birdeye/refs/heads/main/openapi/birdeye-birdeye-api-openapi.yml