Manage contacts across locations effortlessly with a robust Contact Management System.
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.