openapi: 3.1.0
info:
  title: Birdeye Aggregation Contact 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: Contact
  description: Manage contacts across locations effortlessly with a robust Contact Management System.
paths:
  /v1/customer-v2/external/saveCustomer:
    post:
      summary: Create or Update Contact
      operationId: create-or-update-contact
      tags:
      - Contact
      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: 5043
                  message: Contact not found for the given request
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $schema: http://json-schema.org/draft-07/schema#
              type: object
              properties:
                id:
                  type: string
                firstName:
                  type: string
                lastName:
                  type: string
                email:
                  type: string
                phone:
                  type: string
                countryCode:
                  type: string
                smsOptin:
                  type: boolean
                emailOptin:
                  type: boolean
                blocked:
                  type: boolean
                businessIds:
                  type: array
                tags:
                  type: string
                customFields:
                  type: array
                externalId:
                  type: string
  /v1/customer-v2/external/getCustomer:
    post:
      summary: Get Contact
      operationId: get-contact
      tags:
      - Contact
      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: 5043
                  message: Contact not found for the given request
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $schema: http://json-schema.org/draft-07/schema#
              type: object
              properties:
                id:
                  type: string
                cid:
                  type: string
                email:
                  type: string
                phone:
                  type: string
                experienceScore:
                  type: boolean
  /v1/customer-v2/external/deleteCustomer:
    post:
      summary: Delete Contact
      operationId: delete-contact
      tags:
      - Contact
      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: 5043
                  message: Contact not found for the given request
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $schema: http://json-schema.org/draft-07/schema#
              type: object
              properties:
                id:
                  type: string
                businessIds:
                  type: array
              required:
              - id
  /v1/customer/checkin:
    post:
      summary: Customer Checkin
      operationId: customer-checkin
      tags:
      - Contact
      parameters:
      - name: bid
        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: 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:
                name:
                  type: string
                emailId:
                  type: string
                phone:
                  type: string
                smsEnabled:
                  type: number
                additionalParams:
                  type: object
                employees:
                  type: array
                externalId:
                  type: string
  /v1/customer/history/{customerId}:
    get:
      summary: Customer activity log
      operationId: customer-activity-log
      tags:
      - Contact
      parameters:
      - name: businessId
        in: query
        required: true
        description: Id of the business.
        schema:
          type: string
        example: '12345678'
      - name: startDate
        in: query
        required: false
        description: The start date format should be MM/dd/yyyy. if start date is not set, then we will use the date customer was created.
        schema:
          type: string
        example: 12/30/2021
      - name: endDate
        in: query
        required: false
        description: The end date format should be MM/dd/yyyy. if end date is not set, then we will use the current date.
        schema:
          type: string
        example: 12/30/2022
      - name: customerId
        in: path
        required: true
        description: Id of the customer.
        schema:
          type: string
        example: '12344'
      responses:
        '200':
          description: HTTP 200 response
          content:
            application/json:
              schema:
                type: object
                example:
                  code: 1524
                  message: Date entered is invalid.
  /v1/customer/id/{customerId}:
    delete:
      summary: Customer Delete
      operationId: customer-delete
      tags:
      - Contact
      parameters:
      - name: customerId
        in: path
        required: true
        description: Id of enterprise customer.
        schema:
          type: string
        example: '12345678'
      responses:
        '200':
          description: HTTP 200 response
          content:
            application/json:
              schema:
                type: object
                example:
                  code: 1089
                  message: Customer id is invalid.
  /v1/customer-v2/change-permission:
    post:
      summary: Subscribe/Unsubscribe Customer
      operationId: subscribe-unsubscribe-customer
      tags:
      - Contact
      parameters: []
      responses:
        '200':
          description: HTTP 200 response
          content:
            application/json:
              schema:
                type: object
                example:
                  code: 1089
                  message: Customer id is invalid.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $schema: http://json-schema.org/draft-07/schema#
              type: object
              properties:
                permission:
                  type: string
                email:
                  type: array
                phone:
                  type: array
                accountNumber:
                  type: number
              required:
              - accountNumber
  /v2/customer/list:
    post:
      summary: Contact
      operationId: contact
      tags:
      - Contact
      parameters:
      - name: businessId
        in: query
        required: true
        description: Id of the Business.
        schema:
          type: string
        example: '12345678'
      - name: page
        in: query
        required: true
        description: The page number.
        schema:
          type: number
        example: '0'
      - name: size
        in: query
        required: true
        description: Maximum number of contacts return in response.
        schema:
          type: number
        example: '30'
      - name: sortby
        in: query
        required: true
        description: The sorting order of the list.
        schema:
          type: string
        example: lastActivityOn
      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:
                startDate:
                  type: string
                endDate:
                  type: string
  /v1/contact/details:
    post:
      summary: Customer or Lead list
      operationId: customer-or-lead-list
      tags:
      - Contact
      parameters:
      - name: tags
        in: query
        required: false
        description: If tag data is required send true, default value is false.
        schema:
          type: boolean
        example: 'true'
      - name: customfields
        in: query
        required: false
        description: If custom fields data is required send true, default is false.
        schema:
          type: boolean
        example: 'true'
      responses:
        '200':
          description: HTTP 200 response
          content:
            application/json:
              schema:
                type: object
                example:
                  code: 2348
                  message: Max window size allowed is 60000 for a filter selection
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $schema: http://json-schema.org/draft-07/schema#
              type: object
              properties:
                sources:
                  type: array
                startDateUtc:
                  type: string
                endDateUtc:
                  type: string
                contactType:
                  type: string
                businessId:
                  type: number
                page:
                  type: string
                size:
                  type: string
              required:
              - startDateUtc
              - endDateUtc
              - businessId
              - page
              - size
  /v1/contactUs/{businessId}:
    post:
      summary: Contact Us Request
      operationId: contact-us-request
      tags:
      - Contact
      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: 5046
                  message: The customer is blocked
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $schema: http://json-schema.org/draft-07/schema#
              type: object
              properties:
                customerComment:
                  type: string
                customer:
                  type: object
                  properties:
                    name:
                      type: string
                    emailId:
                      type: string
                    phone:
                      type: string
                  required:
                  - name
                additionalParams:
                  type: object
              required:
              - customer
  /v1/contact/{businessId}/update-feed:
    post:
      summary: Get opt-out contact data
      operationId: get-opt-out-contact-data
      tags:
      - Contact
      parameters:
      - name: businessId
        in: path
        required: true
        description: Id of a business (Long).
        schema:
          type: number
        example: '123456'
      responses:
        '200':
          description: HTTP 200 response
          content:
            application/json:
              schema:
                type: object
                example:
                  code: 20083
                  message: End date can't be before start date
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $schema: http://json-schema.org/draft-07/schema#
              type: object
              properties:
                start:
                  type: number
                end:
                  type: number
                subscriptionStatus:
                  type: array
              required:
              - start
              - end
              - subscriptionStatus
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Partner specific API key provided by Birdeye for data exchange.